@radix-ng/primitives 1.0.0-beta.3 → 1.0.0-beta.5

package/fesm2022/radix-ng-primitives-focus-scope.mjs

@@ -1,59 +1,31 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, signal, inject, Injector, DestroyRef, ElementRef, input, booleanAttribute, computed, output, afterNextRender, effect, Directive } from '@angular/core';
+import { effect, InjectionToken, signal, inject, Injector, DestroyRef, ElementRef, input, booleanAttribute, computed, output, afterNextRender, Directive } from '@angular/core';
 import { getActiveElement, createContext } from '@radix-ng/primitives/core';
 
-const RdxFocusScopeConfigToken = new InjectionToken('RdxFocusScopeConfig', {
-    factory: () => ({
-        trapped: signal(false)
-    })
-});
-function provideRdxFocusScopeConfig(factory) {
-    return { provide: RdxFocusScopeConfigToken, useFactory: factory };
-}
-
-function createGlobalState(factory) {
-    const state = factory();
-    return () => state;
+const AUTOFOCUS_ON_MOUNT = 'focusScope.autoFocusOnMount';
+const AUTOFOCUS_ON_UNMOUNT = 'focusScope.autoFocusOnUnmount';
+const EVENT_OPTIONS = { bubbles: false, cancelable: true };
+/**
+ * The real target of a (possibly retargeted) event, piercing shadow boundaries via `composedPath()`.
+ * Falls back to `event.target` when `composedPath` is unavailable.
+ */
+function getEventTarget(event) {
+    return event.composedPath?.()[0] ?? event.target;
 }
-const useFocusStackState = createGlobalState(() => signal([]));
-function createFocusScopesStack() {
-    /** A stack of focus scopes, with the active one at the top */
-    const stack = useFocusStackState();
-    return {
-        add(focusScope) {
-            const current = stack();
-            const active = current[0];
-            if (focusScope !== active) {
-                active?.pause();
-            }
-            const updated = arrayRemove(current, focusScope);
-            updated.unshift(focusScope);
-            stack.set(updated);
-        },
-        remove(focusScope) {
-            const current = stack();
-            const updated = arrayRemove(current, focusScope);
-            stack.set(updated);
-            // после удаления «возобновляем» новый верхний
-            stack()[0]?.resume();
+/**
+ * Shadow-DOM-aware containment: whether `node` is `container` or lives inside it, crossing shadow roots
+ * via their `host` (unlike `Node.contains`, which stops at a shadow boundary).
+ */
+function composedContains(container, node) {
+    let current = node;
+    while (current) {
+        if (current === container) {
+            return true;
         }
-    };
-}
-function arrayRemove(array, item) {
-    const copy = [...array];
-    const idx = copy.indexOf(item);
-    if (idx !== -1) {
-        copy.splice(idx, 1);
+        current = current instanceof ShadowRoot ? current.host : current.parentNode;
     }
-    return copy;
-}
-function removeLinks(items) {
-    return items.filter((el) => el.tagName !== 'A');
+    return false;
 }
-
-const AUTOFOCUS_ON_MOUNT = 'focusScope.autoFocusOnMount';
-const AUTOFOCUS_ON_UNMOUNT = 'focusScope.autoFocusOnUnmount';
-const EVENT_OPTIONS = { bubbles: false, cancelable: true };
 /**
  * Attempts focusing the first element in a list of candidates.
  * Stops when focus has actually moved.
@@ -79,7 +51,7 @@ function focusFirst(candidates, { select = false } = {}) {
  */
 function getTabbableCandidates(container) {
     const nodes = [];
-    const walker = document.createTreeWalker(container, NodeFilter.SHOW_ELEMENT, {
+    const walker = container.ownerDocument.createTreeWalker(container, NodeFilter.SHOW_ELEMENT, {
         acceptNode: (node) => {
             const isHiddenInput = node.tagName === 'INPUT' && node.type === 'hidden';
             if (node.disabled || node.hidden || isHiddenInput)
@@ -97,13 +69,17 @@ function getTabbableCandidates(container) {
     return nodes;
 }
 function isHidden(node, { upTo }) {
-    if (getComputedStyle(node).visibility === 'hidden')
+    const view = node.ownerDocument.defaultView;
+    if (!view) {
+        return false; // no view (detached / SSR) — cannot resolve computed styles, treat as visible
+    }
+    if (view.getComputedStyle(node).visibility === 'hidden')
         return true;
     while (node) {
         // we stop at `upTo` (excluding it)
         if (upTo !== undefined && node === upTo)
             return false;
-        if (getComputedStyle(node).display === 'none')
+        if (view.getComputedStyle(node).display === 'none')
             return true;
         node = node.parentElement;
     }
@@ -130,6 +106,54 @@ function getTabbableEdges(container) {
     const last = findVisible(candidates.reverse(), container);
     return [first, last];
 }
+/** Visible tabbable elements of `root` in document order (the basis for tab-order navigation). */
+function visibleTabbablesIn(root) {
+    return getTabbableCandidates(root).filter((el) => !isHidden(el, { upTo: root }));
+}
+/** The tabbable one step (`dir`) from the document's active element, within `container`. */
+function getTabbableIn(container, dir) {
+    const list = visibleTabbablesIn(container);
+    if (list.length === 0) {
+        return undefined;
+    }
+    const active = getActiveElement(container.ownerDocument);
+    const index = active ? list.indexOf(active) : -1;
+    const nextIndex = index === -1 ? (dir === 1 ? 0 : list.length - 1) : index + dir;
+    return list[nextIndex];
+}
+/**
+ * The next tabbable in the document after the current focus (Base UI `getNextTabbable`) — used by the
+ * portal-focus bridge's trailing guard to step focus past the popup. Falls back to `reference`.
+ */
+function getNextTabbable(reference) {
+    const body = (reference?.ownerDocument ?? document).body;
+    return getTabbableIn(body, 1) ?? reference;
+}
+/** The previous tabbable in the document before the current focus (Base UI `getPreviousTabbable`). */
+function getPreviousTabbable(reference) {
+    const body = (reference?.ownerDocument ?? document).body;
+    return getTabbableIn(body, -1) ?? reference;
+}
+/** The tabbable `dir` steps from `reference` in the document, wrapping around. */
+function getTabbableNearElement(reference, dir) {
+    if (!reference) {
+        return null;
+    }
+    const list = visibleTabbablesIn(reference.ownerDocument.body);
+    const index = list.indexOf(reference);
+    if (list.length === 0 || index === -1) {
+        return null;
+    }
+    return list[(index + dir + list.length) % list.length];
+}
+/** The tabbable immediately after `reference` in the document, wrapping (Base UI `getTabbableAfterElement`). */
+function getTabbableAfterElement(reference) {
+    return getTabbableNearElement(reference, 1);
+}
+/** The tabbable immediately before `reference` in the document, wrapping (Base UI `getTabbableBeforeElement`). */
+function getTabbableBeforeElement(reference) {
+    return getTabbableNearElement(reference, -1);
+}
 function isSelectableInput(element) {
     return element instanceof HTMLInputElement && 'select' in element;
 }
@@ -146,6 +170,190 @@ function focus(element, { select = false } = {}) {
     }
 }
 
+/** Marks the leading / trailing focus-guard spans (Base UI `data-base-ui-focus-guard`). */
+const FOCUS_GUARD_ATTR = 'data-rdx-focus-guard';
+/** Saved-tabindex marker used by {@link disableFocusInside} / {@link enableFocusInside}. */
+const SAVED_TABINDEX_ATTR = 'data-rdx-tabindex';
+/** Visually-hidden, off-flow style for a focus guard / `aria-owns` anchor (Base UI `visuallyHidden`). */
+const FOCUS_GUARD_STYLE = {
+    position: 'fixed',
+    top: '0',
+    left: '0',
+    width: '1px',
+    height: '1px',
+    padding: '0',
+    margin: '-1px',
+    overflow: 'hidden',
+    clipPath: 'inset(50%)',
+    whiteSpace: 'nowrap',
+    border: '0'
+};
+/**
+ * Creates a visually-hidden, **tabbable** focus-guard `<span>` — the Angular counterpart of Base UI's
+ * `FocusGuard`. The portal-focus bridge places one before and one after the portal content so a Tab into
+ * (or out of) the portal lands on a guard, which then redirects focus to the right boundary.
+ */
+function createFocusGuard(ownerDocument) {
+    const guard = ownerDocument.createElement('span');
+    guard.setAttribute('tabindex', '0');
+    guard.setAttribute('aria-hidden', 'true');
+    guard.setAttribute(FOCUS_GUARD_ATTR, '');
+    Object.assign(guard.style, FOCUS_GUARD_STYLE);
+    return guard;
+}
+/**
+ * Creates a visually-hidden `<span aria-owns="…">` that links the portal node into the trigger's tab /
+ * AT order (Base UI's single `aria-owns` anchor). The manager places it next to the trigger.
+ */
+function createAriaOwnsAnchor(ownerDocument, portalId) {
+    const anchor = ownerDocument.createElement('span');
+    anchor.setAttribute('aria-owns', portalId);
+    Object.assign(anchor.style, FOCUS_GUARD_STYLE);
+    return anchor;
+}
+/**
+ * Makes every tabbable descendant of `container` **non-tabbable** (`tabindex="-1"`), saving each one's
+ * original tabindex so {@link enableFocusInside} can restore it. Base UI `disableFocusInside`: a
+ * non-modal portal keeps its content untabbable until focus is actually inside it, so a Tab from the
+ * trigger steps onto the guard instead of jumping into the content.
+ */
+function disableFocusInside(container) {
+    for (const element of getTabbableCandidates(container)) {
+        element.setAttribute(SAVED_TABINDEX_ATTR, element.getAttribute('tabindex') ?? '');
+        element.setAttribute('tabindex', '-1');
+    }
+}
+/** Restores the tabbability that {@link disableFocusInside} suspended. Base UI `enableFocusInside`. */
+function enableFocusInside(container) {
+    container.querySelectorAll(`[${SAVED_TABINDEX_ATTR}]`).forEach((element) => {
+        const original = element.getAttribute(SAVED_TABINDEX_ATTR);
+        element.removeAttribute(SAVED_TABINDEX_ATTR);
+        if (original) {
+            element.setAttribute('tabindex', original);
+        }
+        else {
+            element.removeAttribute('tabindex');
+        }
+    });
+}
+/**
+ * Whether a focus event crossed the `container` boundary — its `relatedTarget` (the other side of the
+ * focus move) is `null` or outside `container` (Base UI `isOutsideEvent`). Shadow-DOM-aware via
+ * {@link composedContains}.
+ */
+function isOutsideEvent(event, container) {
+    const relatedTarget = event.relatedTarget;
+    return !relatedTarget || !composedContains(container, relatedTarget);
+}
+/**
+ * The portal-focus bridge's **tabbability toggle** (Base UI `FloatingPortal` capture-phase `onFocus`).
+ * While `portalNode` is mounted (and `enabled`), it makes the portal content tabbable **only when focus
+ * is inside it**: focus entering from outside re-enables tabbability, focus leaving to outside disables
+ * it again. Listens on the **capture** phase so it settles before the focus manager's guards react.
+ *
+ * Must be called in an injection context. The initial disable-on-mount and the guard-span placement are
+ * the manager's responsibility (Phase 1b); this owns only the dynamic in/out toggle.
+ */
+function useFocusGuardsTabbability(portalNode, options = {}) {
+    const enabled = options.enabled ?? (() => true);
+    let focusInsideDisabled = false;
+    effect((onCleanup) => {
+        const node = portalNode();
+        if (!node || !enabled()) {
+            return;
+        }
+        const ownerDocument = node.ownerDocument;
+        const onFocus = (event) => {
+            // Only react to focus actually crossing the portal boundary.
+            if (!event.relatedTarget || !isOutsideEvent(event, node)) {
+                return;
+            }
+            if (event.type === 'focusin') {
+                if (focusInsideDisabled) {
+                    enableFocusInside(node);
+                    focusInsideDisabled = false;
+                }
+            }
+            else {
+                disableFocusInside(node);
+                focusInsideDisabled = true;
+            }
+        };
+        if (isOutsideEvent(new FocusEvent('focusin', { relatedTarget: ownerDocument.activeElement }), node)) {
+            disableFocusInside(node);
+            focusInsideDisabled = true;
+        }
+        node.addEventListener('focusin', onFocus, true);
+        node.addEventListener('focusout', onFocus, true);
+        onCleanup(() => {
+            node.removeEventListener('focusin', onFocus, true);
+            node.removeEventListener('focusout', onFocus, true);
+            if (focusInsideDisabled) {
+                enableFocusInside(node);
+                focusInsideDisabled = false;
+            }
+        });
+    });
+}
+
+const RdxFocusScopeConfigToken = new InjectionToken('RdxFocusScopeConfig', {
+    factory: () => ({
+        trapped: signal(false)
+    })
+});
+function provideRdxFocusScopeConfig(factory) {
+    return { provide: RdxFocusScopeConfigToken, useFactory: factory };
+}
+
+/**
+ * The active-scope stack pauses/resumes scopes, so it **is** cross-document coordination state — keyed
+ * per owner `Document` (a `WeakMap`) rather than process-global (ADR 0017 Phase 1a): opening a scope in
+ * document B must not pause document A's scope.
+ */
+const stacksByDocument = new WeakMap();
+function getFocusStackState(document) {
+    let state = stacksByDocument.get(document);
+    if (!state) {
+        state = signal([]);
+        stacksByDocument.set(document, state);
+    }
+    return state;
+}
+function createFocusScopesStack(document) {
+    /** A stack of focus scopes for this document, with the active one at the top */
+    const stack = getFocusStackState(document);
+    return {
+        add(focusScope) {
+            const current = stack();
+            const active = current[0];
+            if (focusScope !== active) {
+                active?.pause();
+            }
+            const updated = arrayRemove(current, focusScope);
+            updated.unshift(focusScope);
+            stack.set(updated);
+        },
+        remove(focusScope) {
+            const current = stack();
+            const updated = arrayRemove(current, focusScope);
+            stack.set(updated);
+            // после удаления «возобновляем» новый верхний
+            stack()[0]?.resume();
+        }
+    };
+}
+function arrayRemove(array, item) {
+    const copy = [...array];
+    const idx = copy.indexOf(item);
+    if (idx !== -1) {
+        copy.splice(idx, 1);
+    }
+    return copy;
+}
+function removeLinks(items) {
+    return items.filter((el) => el.tagName !== 'A');
+}
+
 const [injectFocusScopeContext, provideFocusScopeContext] = createContext('FocusScope Context', 'utils/focus-scope');
 const rootContext = () => {
     const context = inject(RdxFocusScope);
@@ -163,6 +371,8 @@ class RdxFocusScope {
         this.destroyRef = inject(DestroyRef);
         this.elementRef = inject(ElementRef);
         this.config = inject(RdxFocusScopeConfigToken);
+        /** The host's owner `Document` — all focus listeners / reads are scoped here, never global `document`. */
+        this.ownerDocument = this.elementRef.nativeElement.ownerDocument ?? document;
         /**
          * When `true`, tabbing from last item will focus first tabbable
          * and shift+tab from first item will focus last tababble.
@@ -195,7 +405,7 @@ class RdxFocusScope {
          */
         this.unmountAutoFocus = output();
         this.lastFocusedElement = signal(null, ...(ngDevMode ? [{ debugName: "lastFocusedElement" }] : /* istanbul ignore next */ []));
-        this.focusScopesStack = createFocusScopesStack();
+        this.focusScopesStack = createFocusScopesStack(this.ownerDocument);
         this.focusScope = {
             paused: signal(false),
             pause: () => this.focusScope.paused.set(true),
@@ -213,8 +423,8 @@ class RdxFocusScope {
                         if (this.focusScope.paused() || !container) {
                             return;
                         }
-                        const target = event.target;
-                        if (this.elementRef.nativeElement.contains(target)) {
+                        const target = getEventTarget(event);
+                        if (composedContains(container, target)) {
                             this.lastFocusedElement.set(target);
                         }
                         else {
@@ -240,12 +450,12 @@ class RdxFocusScope {
                             return;
                         // If the focus has moved to an actual legitimate element (`relatedTarget !== null`)
                         // that is outside the container, we move focus to the last valid focused element inside.
-                        if (!container.contains(relatedTarget)) {
+                        if (!composedContains(container, relatedTarget)) {
                             focus(this.lastFocusedElement(), { select: true });
                         }
                     };
                     const handleMutations = () => {
-                        const isLastFocusedElementExist = container.contains(this.lastFocusedElement());
+                        const isLastFocusedElementExist = composedContains(container, this.lastFocusedElement());
                         if (!isLastFocusedElementExist) {
                             focus(container);
                         }
@@ -254,11 +464,11 @@ class RdxFocusScope {
                     if (container) {
                         mutationObserver.observe(container, { childList: true, subtree: true });
                     }
-                    document.addEventListener('focusin', handleFocusIn);
-                    document.addEventListener('focusout', handleFocusOut);
+                    this.ownerDocument.addEventListener('focusin', handleFocusIn);
+                    this.ownerDocument.addEventListener('focusout', handleFocusOut);
                     onCleanup(() => {
-                        document.removeEventListener('focusin', handleFocusIn);
-                        document.removeEventListener('focusout', handleFocusOut);
+                        this.ownerDocument.removeEventListener('focusin', handleFocusIn);
+                        this.ownerDocument.removeEventListener('focusout', handleFocusOut);
                         mutationObserver.disconnect();
                     });
                 }
@@ -270,8 +480,8 @@ class RdxFocusScope {
                     return;
                 }
                 this.focusScopesStack.add(this.focusScope);
-                const previouslyFocusedElement = getActiveElement();
-                const hasFocusedCandidate = container.contains(previouslyFocusedElement);
+                const previouslyFocusedElement = getActiveElement(this.ownerDocument);
+                const hasFocusedCandidate = composedContains(container, previouslyFocusedElement);
                 const mountEventHandler = (ev) => {
                     if (this.alive)
                         this.mountAutoFocus.emit(ev);
@@ -284,7 +494,7 @@ class RdxFocusScope {
                         focusFirst(removeLinks(getTabbableCandidates(container)), {
                             select: true
                         });
-                        if (getActiveElement() === previouslyFocusedElement)
+                        if (getActiveElement(this.ownerDocument) === previouslyFocusedElement)
                             focus(container);
                     }
                 }
@@ -297,20 +507,45 @@ class RdxFocusScope {
                     container.removeEventListener(AUTOFOCUS_ON_MOUNT, mountEventHandler);
                     const unmountEvent = new CustomEvent(AUTOFOCUS_ON_UNMOUNT, EVENT_OPTIONS);
                     container.dispatchEvent(unmountEvent);
-                    setTimeout(() => {
-                        if (!unmountEvent.defaultPrevented)
-                            focus(previouslyFocusedElement ?? document.body, { select: true });
+                    // Queue the return-focus on the owner window's animation frame (not `setTimeout`),
+                    // so it runs after the unmounting paint settles (ADR 0017 Phase 1a queued focus).
+                    const view = this.ownerDocument.defaultView ?? globalThis;
+                    view.requestAnimationFrame(() => {
+                        // An enclosing focus manager can override the return target (ADR 0017
+                        // `returnFocus`): `false` suppresses it, an element returns there explicitly
+                        // (bypassing the moved-focus guard), `undefined` keeps the default behavior.
+                        const override = this.config.returnFocus?.();
+                        if (override !== false && !unmountEvent.defaultPrevented) {
+                            if (override) {
+                                focus(override, { select: true });
+                            }
+                            else if (!this.shouldPreserveMovedFocus()) {
+                                focus(previouslyFocusedElement ?? this.ownerDocument.body, { select: true });
+                            }
+                        }
                         // we need to remove the listener after we `dispatchEvent`
                         container.removeEventListener(AUTOFOCUS_ON_UNMOUNT, unmountEventHandler);
                         this.focusScopesStack.remove(this.focusScope);
-                    }, 0);
+                    });
                 });
             }, { injector: this.injector });
         });
     }
+    /**
+     * Whether the interaction that unmounted this scope already moved focus to a legitimate element
+     * **outside** it — e.g. an outside press onto an interactive control in a non-modal layer (ADR 0017
+     * §2, finding #3). Returning focus to the previously-focused element would then *steal* it back from
+     * what the user just acted on. Focus that fell to `<body>` / `null` (a backdrop press, Escape, or the
+     * focused element being removed) is **not** "moved" — return focus normally so keyboard users land
+     * back on the trigger. The page never scroll-jumps either way: {@link focus} uses `preventScroll`.
+     */
+    shouldPreserveMovedFocus() {
+        const active = getActiveElement(this.ownerDocument);
+        return (!!active && active !== this.ownerDocument.body && !composedContains(this.elementRef.nativeElement, active));
+    }
     handleKeyDown(event) {
         const isTabKey = event.key === 'Tab' && !event.altKey && !event.ctrlKey && !event.metaKey;
-        const focusedElement = getActiveElement();
+        const focusedElement = getActiveElement(this.ownerDocument);
         if (isTabKey && focusedElement) {
             const container = event.currentTarget;
             const [first, last] = getTabbableEdges(container);
@@ -355,5 +590,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { RdxFocusScope, RdxFocusScopeConfigToken, injectFocusScopeContext, provideFocusScopeContext, provideRdxFocusScopeConfig };
+export { AUTOFOCUS_ON_MOUNT, AUTOFOCUS_ON_UNMOUNT, EVENT_OPTIONS, FOCUS_GUARD_ATTR, FOCUS_GUARD_STYLE, RdxFocusScope, RdxFocusScopeConfigToken, composedContains, createAriaOwnsAnchor, createFocusGuard, disableFocusInside, enableFocusInside, findVisible, focus, focusFirst, getEventTarget, getNextTabbable, getPreviousTabbable, getTabbableAfterElement, getTabbableBeforeElement, getTabbableCandidates, getTabbableEdges, injectFocusScopeContext, isHidden, isOutsideEvent, isSelectableInput, provideFocusScopeContext, provideRdxFocusScopeConfig, useFocusGuardsTabbability };
 //# sourceMappingURL=radix-ng-primitives-focus-scope.mjs.map