/**
 * Accordion
 * =========
 *
 * A framework-agnostic, class-based implementation of the WAI-ARIA Authoring
 * Practices Guide (APG) "Accordion" pattern:
 *
 *   https://www.w3.org/WAI/ARIA/apg/patterns/accordion/
 *
 * This file is intentionally written as a **reference / translation template**:
 * plain, strictly-typed vanilla TypeScript with heavy documentation so it can be
 * hand- or AI-translated into React, Vue, Svelte, etc. without losing any of the
 * accessibility semantics. Prefer clarity over cleverness here.
 *
 * ---------------------------------------------------------------------------
 * Accessibility contract (what the APG requires and what this class guarantees)
 * ---------------------------------------------------------------------------
 *
 * Structure
 *  - Every accordion header is a NATIVE `<button>` wrapped in a heading element
 *    (`<h2>`, `<h3>`, ...). Using a real button means Enter/Space activation,
 *    focusability and the correct role all come "for free" from the platform —
 *    the APG explicitly recommends this. We therefore do NOT add `role="button"`
 *    or manage tabindex on the trigger ourselves.
 *  - The heading only communicates hierarchy; it must NOT carry the button role.
 *    Choose the heading LEVEL (h2/h3/...) in your markup to fit the page outline.
 *
 * States & properties applied to each trigger button
 *  - `aria-expanded`  : "true" when its panel is visible, "false" when hidden.
 *  - `aria-controls`  : id of the panel the button shows/hides.
 *  - `aria-disabled`  : set to "true" ONLY for the currently-open header when the
 *                       accordion does not permit collapsing it (single-open mode
 *                       with `allowToggle: false`). We use `aria-disabled` rather
 *                       than the `disabled` attribute so the header stays focusable
 *                       and discoverable, exactly as the APG describes.
 *
 * Properties applied to each panel
 *  - `role="region"`      : (optional per APG) turns the panel into a landmark so
 *                           screen-reader users can navigate to it. Disable via
 *                           `useRegionRole: false` to avoid landmark proliferation
 *                           when there are many (~6+) simultaneously-open panels.
 *  - `aria-labelledby`    : id of the trigger button, so the region is named by
 *                           its header.
 *  - `hidden`             : toggled to show/hide the panel. Using the `hidden`
 *                           attribute keeps collapsed content out of the a11y tree
 *                           and the tab order without any extra CSS.
 *
 * Keyboard interaction
 *  - Enter / Space        : toggle the focused header. REQUIRED. Handled natively
 *                           by the `<button>` element → we only listen for `click`.
 *  - Tab / Shift+Tab      : move through the page's focusable elements. REQUIRED.
 *                           Native behaviour — nothing to implement.
 *  - Down / Up Arrow      : move focus to the next / previous header. OPTIONAL.
 *  - Home / End           : move focus to the first / last header. OPTIONAL.
 *
 * The optional roving-arrow behaviours are enabled by default (`arrowNavigation`)
 * because they materially improve the experience, but they can be turned off to
 * mirror the "minimal" APG example.
 *
 * ---------------------------------------------------------------------------
 * Expected markup (progressive enhancement)
 * ---------------------------------------------------------------------------
 *
 * The class ENHANCES semantic markup rather than generating it, so the component
 * degrades gracefully without JavaScript and stays easy to author. Provide, in
 * document order, alternating heading→panel pairs inside the root element:
 *
 * ```html
 * <div class="accordion" data-accordion>
 *   <h3 class="accordion__heading">
 *     <button class="accordion__trigger" type="button">Section one</button>
 *   </h3>
 *   <div class="accordion__panel">
 *     <p>Panel one content.</p>
 *   </div>
 *
 *   <h3 class="accordion__heading">
 *     <button class="accordion__trigger" type="button" data-expanded>Section two</button>
 *   </h3>
 *   <div class="accordion__panel">
 *     <p>Panel two content.</p>
 *   </div>
 * </div>
 * ```
 *
 * Notes on the markup:
 *  - Each `.accordion__panel` is paired with the `.accordion__trigger` that
 *    immediately precedes it (the button's heading is the panel's previous
 *    element sibling).
 *  - Mark an item as initially open with `data-expanded` on its trigger button.
 *  - You do NOT need to write any ARIA attributes or ids yourself — the class
 *    wires up `aria-expanded`, `aria-controls`, `role`, `aria-labelledby`,
 *    `hidden`, and generates any missing ids.
 */

/** Options controlling accordion behaviour. All fields are optional. */
export interface AccordionOptions {
  /**
   * Allow several panels to be open at the same time.
   * When `true`, opening one panel never closes another and every panel is
   * always individually collapsible (so `allowToggle` is implied).
   * @default false
   */
  allowMultiple?: boolean;

  /**
   * In single-open mode (`allowMultiple: false`), allow the currently-open
   * panel to be collapsed by clicking its own header (leaving nothing open).
   * When `false`, exactly one panel is always open and the open header is
   * marked `aria-disabled="true"`.
   * Ignored when `allowMultiple` is `true`.
   * @default true
   */
  allowToggle?: boolean;

  /**
   * Enable the OPTIONAL APG arrow-key / Home / End focus movement between
   * headers. Disable to reproduce the minimal (Enter/Space/Tab only) example.
   * @default true
   */
  arrowNavigation?: boolean;

  /**
   * When arrow navigation is on, wrap focus around the ends (Down on the last
   * header focuses the first, and vice versa).
   * @default true
   */
  wrapFocus?: boolean;

  /**
   * Apply `role="region"` + `aria-labelledby` to each panel. Turn off to avoid
   * creating too many landmarks in accordions with many open panels.
   * @default true
   */
  useRegionRole?: boolean;

  /**
   * Prefix used when generating element ids. Useful to keep ids stable/readable.
   * @default "accordion"
   */
  idPrefix?: string;

  /**
   * Callback invoked on every expand/collapse — the same moments the
   * `accordion:toggle` `CustomEvent` fires (see {@link AccordionToggleDetail}).
   * Receives the affected item's index and its new expanded state (plus the
   * trigger/panel elements), so consumers who prefer a plain callback over
   * `addEventListener('accordion:toggle', ...)` don't have to wire one up
   * themselves. Like the event, it is NOT called during initial setup.
   * @default () => {}
   */
  onToggle?: (detail: AccordionToggleDetail) => void;
}

/** Detail payload for the `accordion:toggle` custom event. */
export interface AccordionToggleDetail {
  /** Zero-based index of the affected item. */
  index: number;
  /** Whether the item is now expanded. */
  expanded: boolean;
  /** The trigger button element of the affected item. */
  trigger: HTMLButtonElement;
  /** The panel element of the affected item. */
  panel: HTMLElement;
}

/** Internal representation of one header/panel pair. */
interface AccordionItem {
  /** The heading wrapper element (e.g. `<h3>`). */
  readonly heading: HTMLElement;
  /** The native `<button>` that toggles the panel. */
  readonly trigger: HTMLButtonElement;
  /** The collapsible panel element. */
  readonly panel: HTMLElement;
}

/**
 * Module-level counter guaranteeing unique generated ids across every Accordion
 * instance on the page, so `aria-controls`/`aria-labelledby` never collide.
 */
let uidCounter = 0;

/** CSS selectors for the required markup hooks. Kept here as the single source of truth. */
const SELECTORS = {
  trigger: '.accordion__trigger',
  panel: '.accordion__panel',
} as const;

export class Accordion {
  private readonly root: HTMLElement;
  private readonly options: Required<AccordionOptions>;
  private readonly items: readonly AccordionItem[];

  /**
   * Bound click handler kept as a field so the exact same reference can be
   * removed in `destroy()` (an inline arrow would be a different reference).
   */
  private readonly onClick = (event: MouseEvent): void => {
    const trigger = (event.target as Element | null)?.closest<HTMLButtonElement>(
      SELECTORS.trigger,
    );
    if (!trigger || !this.root.contains(trigger)) return;

    const index = this.items.findIndex((item) => item.trigger === trigger);
    if (index === -1) return;

    this.toggle(index);
  };

  /** Bound keydown handler for the OPTIONAL arrow/Home/End focus movement. */
  private readonly onKeydown = (event: KeyboardEvent): void => {
    const target = event.target as Element | null;
    const currentIndex = this.items.findIndex((item) => item.trigger === target);
    if (currentIndex === -1) return; // key wasn't pressed on one of our headers

    const lastIndex = this.items.length - 1;
    let nextIndex: number | null = null;

    switch (event.key) {
      case 'ArrowDown':
        nextIndex =
          currentIndex === lastIndex
            ? this.options.wrapFocus
              ? 0
              : null
            : currentIndex + 1;
        break;
      case 'ArrowUp':
        nextIndex =
          currentIndex === 0
            ? this.options.wrapFocus
              ? lastIndex
              : null
            : currentIndex - 1;
        break;
      case 'Home':
        nextIndex = 0;
        break;
      case 'End':
        nextIndex = lastIndex;
        break;
      default:
        return; // not a key we handle
    }

    if (nextIndex === null) return;
    // Prevent the browser from scrolling the page for Arrow/Home/End.
    event.preventDefault();
    this.items[nextIndex]?.trigger.focus();
  };

  /**
   * @param root    The accordion container element (the element carrying the
   *                heading/panel pairs). Passing a non-element throws.
   * @param options Behavioural options; see {@link AccordionOptions}.
   */
  constructor(root: HTMLElement, options: AccordionOptions = {}) {
    if (!(root instanceof HTMLElement)) {
      throw new TypeError('Accordion: `root` must be an HTMLElement.');
    }
    this.root = root;

    // Resolve options once into a fully-populated object so the rest of the
    // class never has to deal with `undefined`.
    this.options = {
      allowMultiple: options.allowMultiple ?? false,
      allowToggle: options.allowToggle ?? true,
      arrowNavigation: options.arrowNavigation ?? true,
      wrapFocus: options.wrapFocus ?? true,
      useRegionRole: options.useRegionRole ?? true,
      idPrefix: options.idPrefix ?? 'accordion',
      onToggle: options.onToggle ?? (() => {}),
    };

    this.items = this.collectItems();
    this.setupAria();
    this.bindEvents();
  }

  // ---------------------------------------------------------------------------
  // Setup
  // ---------------------------------------------------------------------------

  /**
   * Discover the header/panel pairs from the markup. Each trigger button's
   * panel is the trigger heading's next element sibling that matches the panel
   * selector, which keeps authoring simple and the pairing unambiguous.
   */
  private collectItems(): AccordionItem[] {
    const triggers = Array.from(
      this.root.querySelectorAll<HTMLButtonElement>(SELECTORS.trigger),
    );

    return triggers.map((trigger, i) => {
      const heading = trigger.closest<HTMLElement>('h1,h2,h3,h4,h5,h6') ?? trigger.parentElement;
      if (!heading) {
        throw new Error(
          `Accordion: trigger #${i} must be wrapped in a heading element.`,
        );
      }

      const panel = heading.nextElementSibling;
      if (!(panel instanceof HTMLElement) || !panel.matches(SELECTORS.panel)) {
        throw new Error(
          `Accordion: trigger #${i} has no adjacent "${SELECTORS.panel}" panel.`,
        );
      }

      return { heading, trigger, panel };
    });
  }

  /**
   * Apply all static ARIA wiring and reconcile the initial open/closed state
   * declared in the markup (`data-expanded` on triggers).
   */
  private setupAria(): void {
    // Which items are requested open in the markup?
    const initiallyOpen = this.items.map((item) =>
      item.trigger.hasAttribute('data-expanded'),
    );

    // In single-open mode at most one item may start open. Keep the first.
    if (!this.options.allowMultiple) {
      let seenOpen = false;
      for (let i = 0; i < initiallyOpen.length; i++) {
        if (initiallyOpen[i] && seenOpen) initiallyOpen[i] = false;
        else if (initiallyOpen[i]) seenOpen = true;
      }
      // Single-open + no-toggle means one panel must ALWAYS be open. If the
      // author didn't mark one, default to the first item.
      if (!seenOpen && !this.options.allowToggle && initiallyOpen.length > 0) {
        initiallyOpen[0] = true;
      }
    }

    this.items.forEach((item, i) => {
      const uid = `${this.options.idPrefix}-${++uidCounter}`;
      // Ensure both elements have ids so aria-controls / aria-labelledby resolve.
      if (!item.trigger.id) item.trigger.id = `${uid}-trigger`;
      if (!item.panel.id) item.panel.id = `${uid}-panel`;

      item.trigger.setAttribute('aria-controls', item.panel.id);

      if (this.options.useRegionRole) {
        item.panel.setAttribute('role', 'region');
        item.panel.setAttribute('aria-labelledby', item.trigger.id);
      }

      // Clean up the authoring hint so it doesn't linger in the DOM.
      item.trigger.removeAttribute('data-expanded');

      this.setExpanded(i, initiallyOpen[i] ?? false, { silent: true });
    });
  }

  /** Attach delegated event listeners on the root. */
  private bindEvents(): void {
    this.root.addEventListener('click', this.onClick);
    if (this.options.arrowNavigation) {
      this.root.addEventListener('keydown', this.onKeydown);
    }
  }

  // ---------------------------------------------------------------------------
  // Public API
  // ---------------------------------------------------------------------------

  /** Number of header/panel pairs managed by this instance. */
  get length(): number {
    return this.items.length;
  }

  /** Whether the item at `index` is currently expanded. */
  isExpanded(index: number): boolean {
    return this.items[index]?.trigger.getAttribute('aria-expanded') === 'true';
  }

  /** Expand the item at `index` (no-op if already open or index invalid). */
  expand(index: number): void {
    if (!this.items[index] || this.isExpanded(index)) return;

    // Single-open mode: opening one closes any other open panel.
    if (!this.options.allowMultiple) {
      this.items.forEach((_, i) => {
        if (i !== index && this.isExpanded(i)) this.setExpanded(i, false);
      });
    }
    this.setExpanded(index, true);
  }

  /** Collapse the item at `index`, honouring the always-one-open rule. */
  collapse(index: number): void {
    if (!this.items[index] || !this.isExpanded(index)) return;

    // In single-open + no-toggle mode the open panel may not be collapsed.
    if (!this.options.allowMultiple && !this.options.allowToggle) return;

    this.setExpanded(index, false);
  }

  /** Toggle the item at `index` based on its current state. */
  toggle(index: number): void {
    if (this.isExpanded(index)) this.collapse(index);
    else this.expand(index);
  }

  /**
   * Remove all listeners added by this instance. ARIA attributes are left in
   * place (they remain valid); call this before discarding the DOM subtree or
   * re-initialising to avoid duplicate listeners / leaks.
   */
  destroy(): void {
    this.root.removeEventListener('click', this.onClick);
    this.root.removeEventListener('keydown', this.onKeydown);
  }

  // ---------------------------------------------------------------------------
  // Internal state mutation
  // ---------------------------------------------------------------------------

  /**
   * The single low-level function that flips one item's state and keeps every
   * ARIA attribute + the `hidden` attribute in sync. All public mutators funnel
   * through here so the DOM can never drift out of a valid ARIA state.
   *
   * @param index   Which item to change.
   * @param expanded Target state.
   * @param opts.silent When true, suppress the `accordion:toggle` event and the
   *                    `onToggle` callback (used during initial setup so
   *                    listeners don't fire on load).
   */
  private setExpanded(
    index: number,
    expanded: boolean,
    opts: { silent?: boolean } = {},
  ): void {
    const item = this.items[index];
    if (!item) return;

    item.trigger.setAttribute('aria-expanded', String(expanded));
    item.panel.hidden = !expanded;

    // Reconcile aria-disabled for the "always one open" configuration: the open
    // header must advertise that it cannot be collapsed.
    const lockOpenHeader = !this.options.allowMultiple && !this.options.allowToggle;
    if (lockOpenHeader && expanded) {
      item.trigger.setAttribute('aria-disabled', 'true');
    } else {
      item.trigger.removeAttribute('aria-disabled');
    }

    if (!opts.silent) {
      const detail: AccordionToggleDetail = {
        index,
        expanded,
        trigger: item.trigger,
        panel: item.panel,
      };
      this.options.onToggle(detail);
      this.root.dispatchEvent(
        new CustomEvent<AccordionToggleDetail>('accordion:toggle', {
          detail,
          bubbles: true,
        }),
      );
    }
  }
}