gitea/web_src/js/modules/observer.ts

import {isDocumentFragmentOrElementNode} from '../utils/dom.ts';
import type {Promisable} from '../types.ts';
import type {InitPerformanceTracer} from './init.ts';

let globalSelectorObserverInited = false;

type SelectorHandler = {selector: string, handler: (el: HTMLElement) => void};
const selectorHandlers: SelectorHandler[] = [];

type GlobalEventFunc<T extends HTMLElement, E extends Event> = (el: T, e: E) => Promisable<void>;
const globalEventFuncs: Record<string, GlobalEventFunc<HTMLElement, Event>> = {};

type GlobalInitFunc<T extends HTMLElement> = (el: T) => Promisable<void>;
const globalInitFuncs: Record<string, GlobalInitFunc<HTMLElement>> = {};

// It handles the global events for all `<div data-global-click="onSomeElemClick"></div>` elements.
export function registerGlobalEventFunc<T extends HTMLElement, E extends Event>(event: string, name: string, func: GlobalEventFunc<T, E>) {
  globalEventFuncs[`${event}:${name}`] = func as GlobalEventFunc<HTMLElement, Event>;
}

// It handles the global init functions by a selector, for example:
// > registerGlobalSelectorObserver('.ui.dropdown:not(.custom)', (el) => { initDropdown(el, ...) });
// ATTENTION: For most cases, it's recommended to use registerGlobalInitFunc instead,
// Because this selector-based approach is less efficient and less maintainable.
// But if there are already a lot of elements on many pages, this selector-based approach is more convenient for exiting code.
export function registerGlobalSelectorFunc(selector: string, handler: (el: HTMLElement) => void) {
  selectorHandlers.push({selector, handler});
  // Then initAddedElementObserver will call this handler for all existing elements after all handlers are added.
  // This approach makes the init stage only need to do one "querySelectorAll".
  if (!globalSelectorObserverInited) return;
  for (const el of document.querySelectorAll<HTMLElement>(selector)) {
    handler(el);
  }
}

// It handles the global init functions for all `<div data-global-int="initSomeElem"></div>` elements.
export function registerGlobalInitFunc<T extends HTMLElement>(name: string, handler: GlobalInitFunc<T>) {
  globalInitFuncs[name] = handler as GlobalInitFunc<HTMLElement>;
  // The "global init" functions are managed internally and called by callGlobalInitFunc
  // They must be ready before initGlobalSelectorObserver is called.
  if (globalSelectorObserverInited) throw new Error('registerGlobalInitFunc() must be called before initGlobalSelectorObserver()');
}

function callGlobalInitFunc(el: HTMLElement) {
  // TODO: GLOBAL-INIT-MULTIPLE-FUNCTIONS: maybe in the future we need to extend it to support multiple functions, for example: `data-global-init="func1 func2 func3"`
  const initFunc = el.getAttribute('data-global-init')!;
  const func = globalInitFuncs[initFunc];
  if (!func) throw new Error(`Global init function "${initFunc}" not found`);

  // when an element node is removed and added again, it should not be re-initialized again.
  type GiteaGlobalInitElement = Partial<HTMLElement> & {_giteaGlobalInited: boolean};
  if ((el as GiteaGlobalInitElement)._giteaGlobalInited) return;
  (el as GiteaGlobalInitElement)._giteaGlobalInited = true;

  func(el);
}

function initKeyboardShortcutKbd(kbd: HTMLElement) {
  // Handle initial state: hide the kbd hint if the associated input already has a value
  // (e.g., from browser autofill or back/forward navigation cache)
  const input = kbd.parentElement?.querySelector<HTMLInputElement>('input, textarea, select');
  if (input?.value) kbd.style.display = 'none';
}

function attachGlobalEvents() {
  // add global "[data-global-click]" event handler
  document.addEventListener('click', (e) => {
    const elem = (e.target as HTMLElement).closest<HTMLElement>('[data-global-click]');
    if (!elem) return;
    const funcName = elem.getAttribute('data-global-click');
    const func = globalEventFuncs[`click:${funcName}`];
    if (!func) throw new Error(`Global event function "click:${funcName}" not found`);
    func(elem, e);
  });

  // add global "kbd[data-global-keyboard-shortcut]" event handlers
  // A <kbd> element next to an <input> declares a keyboard shortcut for that input.
  // When the matching key is pressed, the sibling input is focused.
  // When Escape is pressed inside such an input, the input is cleared and blurred.
  // The <kbd> element is shown/hidden automatically based on input focus and value.
  document.addEventListener('keydown', (e: KeyboardEvent) => {
    const target = e.target as HTMLElement;

    // Handle Escape: clear and blur inputs that have an associated keyboard shortcut
    if (e.key === 'Escape' && target.matches('input, textarea, select')) {
      const kbd = target.parentElement?.querySelector<HTMLElement>('kbd[data-global-keyboard-shortcut]');
      if (kbd) {
        (target as HTMLInputElement).value = '';
        (target as HTMLInputElement).blur();
        return;
      }
    }

    // Don't trigger shortcuts when typing in input fields or contenteditable areas
    if (target.matches('input, textarea, select') || target.isContentEditable) {
      return;
    }

    // Don't trigger shortcuts when modifier keys are pressed
    if (e.ctrlKey || e.metaKey || e.altKey) {
      return;
    }

    // Find kbd element with matching shortcut (case-insensitive), then focus its sibling input
    const key = e.key.toLowerCase();
    const escapedKey = CSS.escape(key);
    const kbd = document.querySelector<HTMLElement>(`kbd[data-global-keyboard-shortcut="${escapedKey}"]`);
    if (!kbd) return;

    e.preventDefault();
    const input = kbd.parentElement?.querySelector<HTMLInputElement>('input, textarea, select');
    if (input) input.focus();
  });

  // Toggle kbd shortcut hint visibility on input focus/blur
  document.addEventListener('focusin', (e) => {
    const target = e.target as HTMLElement;
    if (!target.matches('input, textarea, select')) return;
    const kbd = target.parentElement?.querySelector<HTMLElement>('kbd[data-global-keyboard-shortcut]');
    if (kbd) kbd.style.display = 'none';
  });

  document.addEventListener('focusout', (e) => {
    const target = e.target as HTMLElement;
    if (!target.matches('input, textarea, select')) return;
    const kbd = target.parentElement?.querySelector<HTMLElement>('kbd[data-global-keyboard-shortcut]');
    if (kbd) kbd.style.display = (target as HTMLInputElement).value ? 'none' : '';
  });
}

export function initGlobalSelectorObserver(perfTracer: InitPerformanceTracer | null): void {
  if (globalSelectorObserverInited) throw new Error('initGlobalSelectorObserver() already called');
  globalSelectorObserverInited = true;

  attachGlobalEvents();

  selectorHandlers.push({selector: '[data-global-init]', handler: callGlobalInitFunc});
  selectorHandlers.push({selector: 'kbd[data-global-keyboard-shortcut]', handler: initKeyboardShortcutKbd});
  const observer = new MutationObserver((mutationList) => {
    const len = mutationList.length;
    for (let i = 0; i < len; i++) {
      const mutation = mutationList[i];
      const len = mutation.addedNodes.length;
      for (let i = 0; i < len; i++) {
        const addedNode = mutation.addedNodes[i] as HTMLElement;
        if (!isDocumentFragmentOrElementNode(addedNode)) continue;

        for (const {selector, handler} of selectorHandlers) {
          if (addedNode.matches(selector)) {
            handler(addedNode);
          }
          for (const el of addedNode.querySelectorAll<HTMLElement>(selector)) {
            handler(el);
          }
        }
      }
    }
  });
  if (perfTracer) {
    for (const {selector, handler} of selectorHandlers) {
      perfTracer.recordCall(`initGlobalSelectorObserver ${selector}`, () => {
        for (const el of document.querySelectorAll<HTMLElement>(selector)) {
          handler(el);
        }
      });
    }
  } else {
    for (const {selector, handler} of selectorHandlers) {
      for (const el of document.querySelectorAll<HTMLElement>(selector)) {
        handler(el);
      }
    }
  }
  observer.observe(document, {subtree: true, childList: true});
}