/**
 * Focus Trap Utility
 *
 * Mirrors official USWDS focus trap behavior for managing keyboard focus
 *
 * SOURCE: uswds-core/src/js/utils/focus-trap.js (Lines 1-85)
 * @uswds-source https://github.com/uswds/uswds/blob/develop/packages/uswds-core/src/js/utils/focus-trap.js
 * @uswds-version 3.8.0
 * @last-synced 2025-10-05
 * @sync-status ✅ UP TO DATE
 *
 * CRITICAL: This file replicates USWDS source code to maintain 100% behavior parity.
 * DO NOT add custom logic. ALL changes must come from USWDS source updates.
 */

/**
 * Focusable elements selector
 *
 * SOURCE: focus-trap.js (Lines 6-7)
 */
const FOCUSABLE =
  'a[href], area[href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), button:not([disabled]), iframe, object, embed, [tabindex="0"], [contenteditable]';

/**
 * Get active element
 *
 * SOURCE: active-element.js (Line 1)
 *
 * @param htmlDocument - Document to get active element from
 * @returns Active element
 */
function getActiveElement(htmlDocument: Document = document): Element | null {
  return htmlDocument.activeElement;
}

/**
 * Select elements from DOM
 *
 * SOURCE: select.js (Lines 10-28)
 *
 * @param selector - CSS selector
 * @param context - Context element
 * @returns Array of elements
 */
function selectElements(selector: string, context: Element | Document): Element[] {
  const selection = context.querySelectorAll(selector);
  return Array.prototype.slice.call(selection);
}

/**
 * Tab handler
 *
 * SOURCE: focus-trap.js (Lines 9-43)
 *
 * @param context - Context element containing focusable elements
 * @returns Tab handler object
 */
function tabHandler(context: Element) {
  const focusableElements = selectElements(FOCUSABLE, context);
  const firstTabStop = focusableElements[0] as HTMLElement;
  const lastTabStop = focusableElements[focusableElements.length - 1] as HTMLElement;

  /**
   * Tab ahead handler
   *
   * SOURCE: focus-trap.js (Lines 16-21)
   */
  function tabAhead(event: KeyboardEvent): void {
    if (getActiveElement() === lastTabStop) {
      event.preventDefault();
      firstTabStop.focus();
    }
  }

  /**
   * Tab back handler
   *
   * SOURCE: focus-trap.js (Lines 23-35)
   */
  function tabBack(event: KeyboardEvent): void {
    if (getActiveElement() === firstTabStop) {
      event.preventDefault();
      lastTabStop.focus();
    }
    // This checks if you want to set the initial focus to a container
    // instead of an element within, and the user tabs back.
    // Then we set the focus to the first
    else if (!focusableElements.includes(getActiveElement() as Element)) {
      event.preventDefault();
      firstTabStop.focus();
    }
  }

  return {
    firstTabStop,
    lastTabStop,
    tabAhead,
    tabBack,
  };
}

/**
 * Focus trap behavior controller
 */
interface FocusTrapController {
  on: () => void;
  off: () => void;
  update: (isActive: boolean) => void;
}

/**
 * Key bindings map
 */
type KeyBindings = Record<string, (event: KeyboardEvent) => void>;

/**
 * Create focus trap
 *
 * SOURCE: focus-trap.js (Lines 45-84)
 *
 * @param context - Context element to trap focus within
 * @param additionalKeyBindings - Additional key bindings (e.g., Escape handler)
 * @returns Focus trap controller
 */
export function FocusTrap(
  context: Element,
  additionalKeyBindings: KeyBindings = {}
): FocusTrapController {
  const tabEventHandler = tabHandler(context);
  const bindings = { ...additionalKeyBindings };
  const { Esc, Escape } = bindings;

  if (Escape && !Esc) bindings.Esc = Escape;

  let isActive = false;

  /**
   * Handle keydown events
   *
   * SOURCE: Implements keymap behavior from focus-trap.js (Lines 55-59)
   */
  const handleKeydown = (event: KeyboardEvent): void => {
    if (!isActive) return;

    const key = event.shiftKey ? `Shift+${event.key}` : event.key;

    // Tab navigation
    if (key === 'Tab') {
      tabEventHandler.tabAhead(event);
    } else if (key === 'Shift+Tab') {
      tabEventHandler.tabBack(event);
    }
    // Additional key bindings
    else if (bindings[key]) {
      bindings[key](event);
    }
    // Handle Esc/Escape
    else if ((event.key === 'Esc' || event.key === 'Escape') && bindings.Esc) {
      bindings.Esc(event);
    }
  };

  /**
   * Initialize focus trap
   *
   * SOURCE: focus-trap.js (Lines 66-72)
   */
  function init(): void {
    // NOTE: This TODO is copied verbatim from USWDS source code (focus-trap.js line 68)
    // USWDS team's original question: "is this desirable behavior? Should the trap always
    // do this by default or should the component getting decorated handle this?"
    // We maintain this behavior exactly as USWDS implements it for 100% parity.
    if (tabEventHandler.firstTabStop) {
      tabEventHandler.firstTabStop.focus();
    }
  }

  /**
   * Add event listeners
   *
   * SOURCE: Implements behavior pattern from focus-trap.js (Lines 61-81)
   */
  function add(): void {
    document.addEventListener('keydown', handleKeydown);
  }

  /**
   * Remove event listeners
   *
   * SOURCE: Implements behavior pattern from focus-trap.js (Lines 61-81)
   */
  function remove(): void {
    document.removeEventListener('keydown', handleKeydown);
  }

  /**
   * Activate focus trap
   *
   * SOURCE: Implements behavior.on() from focus-trap.js (Line 27)
   */
  function on(): void {
    init();
    add();
    isActive = true;
  }

  /**
   * Deactivate focus trap
   *
   * SOURCE: Implements behavior.off() from focus-trap.js (Line 28)
   */
  function off(): void {
    remove();
    isActive = false;
  }

  /**
   * Update focus trap state
   *
   * SOURCE: focus-trap.js (Lines 73-79)
   *
   * @param active - Whether focus trap should be active
   */
  function update(active: boolean): void {
    if (active) {
      on();
    } else {
      off();
    }
  }

  return {
    on,
    off,
    update,
  };
}