@envive-ai/react-hooks 0.3.40 → 0.3.41

package/src/hooks/FocusTrap/__tests__/useFocusTrap.test.tsx

@@ -0,0 +1,236 @@
+import { act, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { useRef, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { useFocusTrap } from '../useFocusTrap';
+
+const TestDialog = ({ enabled }: { enabled: boolean }) => {
+  const ref = useRef<HTMLDivElement>(null);
+  useFocusTrap(ref, enabled);
+  return enabled ? (
+    <div
+      ref={ref}
+      data-testid="dialog"
+      role="dialog"
+    >
+      <button
+        type="button"
+        data-testid="close"
+      >
+        Close
+      </button>
+      <input data-testid="input" />
+      <button
+        type="button"
+        data-testid="action"
+      >
+        Action
+      </button>
+    </div>
+  ) : null;
+};
+
+const LazyContentDialog = () => {
+  const ref = useRef<HTMLDivElement>(null);
+  const [loaded, setLoaded] = useState(false);
+  useFocusTrap(ref, true);
+  return (
+    <div>
+      <button
+        type="button"
+        data-testid="load"
+        onClick={() => setLoaded(true)}
+      >
+        Load
+      </button>
+      <div
+        ref={ref}
+        data-testid="dialog"
+        role="dialog"
+      >
+        {loaded && (
+          <>
+            <button
+              type="button"
+              data-testid="close"
+            >
+              Close
+            </button>
+            <button
+              type="button"
+              data-testid="action"
+            >
+              Action
+            </button>
+          </>
+        )}
+      </div>
+    </div>
+  );
+};
+
+describe('useFocusTrap', () => {
+  it('moves focus to the first focusable element inside the container when enabled', () => {
+    render(<TestDialog enabled />);
+    expect(screen.getByTestId('close')).toHaveFocus();
+  });
+
+  it('does nothing while disabled', () => {
+    const { container } = render(
+      <>
+        <button
+          type="button"
+          data-testid="outside"
+        >
+          Outside
+        </button>
+        <TestDialog enabled={false} />
+      </>,
+    );
+    const outside = screen.getByTestId('outside');
+    outside.focus();
+    expect(outside).toHaveFocus();
+    expect(container.querySelector('[data-testid="dialog"]')).toBeNull();
+  });
+
+  it('wraps Tab from the last focusable back to the first', async () => {
+    const user = userEvent.setup();
+    render(<TestDialog enabled />);
+    const close = screen.getByTestId('close');
+    const action = screen.getByTestId('action');
+
+    expect(close).toHaveFocus();
+    action.focus();
+    expect(action).toHaveFocus();
+
+    await user.tab();
+    expect(close).toHaveFocus();
+  });
+
+  it('wraps Shift+Tab from the first focusable back to the last', async () => {
+    const user = userEvent.setup();
+    render(<TestDialog enabled />);
+    const close = screen.getByTestId('close');
+    const action = screen.getByTestId('action');
+
+    expect(close).toHaveFocus();
+
+    await user.tab({ shift: true });
+    expect(action).toHaveFocus();
+  });
+
+  it('restores focus to the previously focused element on disable', () => {
+    const Wrapper = () => {
+      const [open, setOpen] = useState(false);
+      return (
+        <div>
+          <button
+            type="button"
+            data-testid="trigger"
+            onClick={() => setOpen(true)}
+          >
+            Open
+          </button>
+          {open && (
+            <button
+              type="button"
+              data-testid="programmatic-close"
+              onClick={() => setOpen(false)}
+            >
+              Programmatic close
+            </button>
+          )}
+          <TestDialog enabled={open} />
+        </div>
+      );
+    };
+    render(<Wrapper />);
+    const trigger = screen.getByTestId('trigger');
+    trigger.focus();
+    expect(trigger).toHaveFocus();
+
+    act(() => {
+      trigger.click();
+    });
+    expect(screen.getByTestId('close')).toHaveFocus();
+
+    act(() => {
+      screen.getByTestId('programmatic-close').click();
+    });
+    expect(trigger).toHaveFocus();
+  });
+
+  it('waits for lazy content and focuses the first focusable when it appears', async () => {
+    render(<LazyContentDialog />);
+    const load = screen.getByTestId('load');
+    expect(load).not.toHaveFocus();
+
+    await act(async () => {
+      load.click();
+    });
+
+    expect(screen.getByTestId('close')).toHaveFocus();
+  });
+
+  it('keeps focus moving freely inside the trap when the container lives in a shadow root', () => {
+    // Build the host + shadow root manually so we can mount our React tree inside it.
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const shadow = host.attachShadow({ mode: 'open' });
+    const mountPoint = document.createElement('div');
+    shadow.appendChild(mountPoint);
+
+    const ShadowDialog = () => {
+      const ref = useRef<HTMLDivElement>(null);
+      useFocusTrap(ref, true);
+      return (
+        <div
+          ref={ref}
+          data-testid="shadow-dialog"
+        >
+          <button
+            type="button"
+            data-testid="shadow-close"
+          >
+            Close
+          </button>
+          <button
+            type="button"
+            data-testid="shadow-action"
+          >
+            Action
+          </button>
+        </div>
+      );
+    };
+
+    // Render React into the shadow root mount point via createRoot to make sure
+    // we are exercising the shadow-DOM-aware code paths.
+    const reactRoot = createRoot(mountPoint);
+    act(() => {
+      reactRoot.render(<ShadowDialog />);
+    });
+
+    const close = shadow.querySelector('[data-testid="shadow-close"]') as HTMLButtonElement;
+    const action = shadow.querySelector('[data-testid="shadow-action"]') as HTMLButtonElement;
+    expect(shadow.activeElement).toBe(close);
+
+    // Manually move focus to the action button (mimicking a Tab away from first)
+    // and dispatch a non-shift Tab. The handler should NOT preventDefault because
+    // the active element is inside the container (verified via shadow root).
+    action.focus();
+    expect(shadow.activeElement).toBe(action);
+
+    const evt = new KeyboardEvent('keydown', { key: 'Tab', bubbles: true, cancelable: true });
+    act(() => {
+      action.dispatchEvent(evt);
+    });
+    // Since action is `last`, the trap wraps focus back to `close`.
+    expect(shadow.activeElement).toBe(close);
+
+    act(() => {
+      reactRoot.unmount();
+    });
+    host.remove();
+  });
+});

package/src/hooks/FocusTrap/index.ts

@@ -0,0 +1 @@
+export * from './useFocusTrap';

package/src/hooks/FocusTrap/useFocusTrap.ts

@@ -0,0 +1,125 @@
+import { RefObject, useEffect } from 'react';
+
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  'input:not([disabled]):not([type="hidden"])',
+  'textarea:not([disabled])',
+  'select:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(',');
+
+const isElementVisible = (el: HTMLElement): boolean => {
+  if (el.hasAttribute('hidden')) return false;
+  if (typeof window === 'undefined') return true;
+  const style = window.getComputedStyle(el);
+  return style.display !== 'none' && style.visibility !== 'hidden';
+};
+
+const getFocusableElements = (container: HTMLElement): HTMLElement[] =>
+  Array.from(container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter(isElementVisible);
+
+/**
+ * Returns the deepest active element across (possibly nested) shadow roots,
+ * starting from the document. Plain `document.activeElement` returns the shadow
+ * host when focus is inside an open shadow root, so we recurse into shadowRoot
+ * to find the truly focused element.
+ */
+const getDeepActiveElement = (): HTMLElement | null => {
+  if (typeof document === 'undefined') return null;
+  let active = document.activeElement as HTMLElement | null;
+  while (active && active.shadowRoot && active.shadowRoot.activeElement) {
+    active = active.shadowRoot.activeElement as HTMLElement;
+  }
+  return active;
+};
+
+/**
+ * Trap keyboard focus inside `containerRef` while `enabled` is true.
+ *
+ * On enable: moves focus to the first focusable element inside the container.
+ * If the container is empty (e.g. lazy-loaded content), waits for DOM mutations
+ * and focuses the first focusable as soon as it appears.
+ *
+ * While enabled: Tab and Shift+Tab wrap around so focus stays inside.
+ *
+ * On disable: restores focus to the previously focused element if it is still
+ * present in the document.
+ */
+export const useFocusTrap = (containerRef: RefObject<HTMLElement | null>, enabled: boolean) => {
+  useEffect(() => {
+    if (!enabled || typeof document === 'undefined') return undefined;
+
+    const container = containerRef.current;
+    if (!container) return undefined;
+
+    // The container may live inside a Shadow DOM (the injection bundle hosts
+    // the chat that way). Use the container's root so containment checks and
+    // active-element lookups work both in the light DOM and inside shadow roots.
+    const root = container.getRootNode() as Document | ShadowRoot;
+    const previouslyFocused = getDeepActiveElement();
+
+    const getActiveElement = (): HTMLElement | null => root.activeElement as HTMLElement | null;
+
+    const focusFirst = (): boolean => {
+      const focusables = getFocusableElements(container);
+      const first = focusables[0];
+      if (first) {
+        first.focus();
+        return true;
+      }
+      return false;
+    };
+
+    let observer: MutationObserver | null = null;
+    if (!focusFirst()) {
+      observer = new MutationObserver(() => {
+        if (focusFirst()) {
+          observer?.disconnect();
+          observer = null;
+        }
+      });
+      observer.observe(container, { childList: true, subtree: true });
+    }
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab') return;
+
+      const focusables = getFocusableElements(container);
+      if (focusables.length === 0) {
+        e.preventDefault();
+        return;
+      }
+
+      const first = focusables[0];
+      const last = focusables[focusables.length - 1];
+      const active = getActiveElement();
+      const isInsideContainer = active ? container.contains(active) : false;
+
+      if (e.shiftKey) {
+        if (active === first || !isInsideContainer) {
+          e.preventDefault();
+          last.focus();
+        }
+      } else if (active === last || !isInsideContainer) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
+
+    container.addEventListener('keydown', handleKeyDown);
+
+    return () => {
+      observer?.disconnect();
+      container.removeEventListener('keydown', handleKeyDown);
+
+      if (
+        previouslyFocused &&
+        typeof previouslyFocused.focus === 'function' &&
+        previouslyFocused.isConnected
+      ) {
+        previouslyFocused.focus();
+      }
+    };
+  }, [enabled, containerRef]);
+};