Events

declare const target: EventTarget;
declare const listener: EventListenerOrEventListenerObject;
 
target.addEventListener("click", listener);
target.addEventListener("click", listener, true); // capture
target.addEventListener("click", listener, {
  capture: false,
  once: true,
  passive: true,
  signal: AbortSignal.timeout(5_000),
});

const outer = document.querySelector("#outer");
const log = (e: Event) =>
  console.info(e.currentTarget, e.eventPhase);
 
outer?.addEventListener("click", log, { capture: true });
// capture listener runs first, then the bubble one
outer?.addEventListener("click", log);
// e.composedPath(): [target, …ancestors, document, window]

type Action = "edit" | "delete";
const isAction = (v: string | undefined): v is Action =>
  v === "edit" || v === "delete";
 
const list = document.querySelector("ul#todos");
 
list?.addEventListener("click", (e) => {
  // text nodes etc.
  if (!(e.target instanceof Element)) return;
  const btn = e.target.closest<HTMLButtonElement>(
    "button[data-action]",
  );
  if (!btn || !list.contains(btn)) return;
 
  const id = btn.closest("li")?.dataset.id;
  const action = btn.dataset.action;
  if (id && isAction(action)) run(action, id);
});
 
function run(action: Action, id: string): void {
  /* … */
}

document.addEventListener("DOMContentLoaded", init, {
  once: true,
});
function init(): void { /* safe to query the DOM */ }
 
// save state when the tab is hidden: the last
// reliable moment
document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "hidden") {
    navigator.sendBeacon("/analytics", JSON.stringify({}));
  }
});
 
window.addEventListener("pagehide", (e) => {
  if (e.persisted) { /* page entering back/forward cache */ }
});

const isMac = /Mac|iPhone|iPad/.test(navigator.userAgent);
 
document.addEventListener("keydown", (e) => {
  if (e.isComposing || e.repeat) return;
  const mod = isMac ? e.metaKey : e.ctrlKey;
 
  if (mod && e.key.toLowerCase() === "k") {
    e.preventDefault(); // stop the browser's own shortcut
    openSearch();
  } else if (e.key === "Escape") {
    closeSearch();
  }
});
declare function openSearch(): void;
declare function closeSearch(): void;

const handle =
  document.querySelector<HTMLElement>(".handle");
 
handle?.addEventListener("pointerdown", (e) => {
  if (e.button !== 0) return;
  handle.setPointerCapture(e.pointerId); // keep events
  const startX = e.clientX - handle.offsetLeft;
 
  const move = (ev: PointerEvent) => {
    handle.style.left = `${ev.clientX - startX}px`;
  };
  handle.addEventListener("pointermove", move);
  handle.addEventListener("lostpointercapture", () => {
    handle.removeEventListener("pointermove", move);
  }, { once: true });
});

const form = document.querySelector("form");
 
form?.addEventListener("submit", (e) => {
  e.preventDefault(); // no page navigation
  const data = new FormData(form, e.submitter);
  void fetch(form.action, { method: "POST", body: data });
});
 
// passive: preventDefault is ignored (with a
// console warning)
window.addEventListener("wheel", (e) => e.preventDefault(), {
  passive: false, // required to block scrolling
});

type AddToCart = { sku: string; qty: number };
 
const evt = new CustomEvent<AddToCart>("cart:add", {
  detail: { sku: "A-1", qty: 2 },
  bubbles: true,     // default false
  cancelable: true,  // allow preventDefault
  composed: true,    // cross shadow DOM boundaries
});
 
const ok = document
  .querySelector("#buy")
  ?.dispatchEvent(evt);
// dispatchEvent is synchronous: listeners have already run

type AddToCart = { sku: string; qty: number };
 
declare global {
  interface HTMLElementEventMap {
    "cart:add": CustomEvent<AddToCart>;
  }
  interface WindowEventMap {
    "cart:add": CustomEvent<AddToCart>;
  }
}
 
window.addEventListener("cart:add", (e) => {
  e.detail.qty; // number
});

class Emitter<D extends Record<string, unknown>>
  extends EventTarget {
  on<K extends keyof D & string>(
    type: K,
    fn: (e: CustomEvent<D[K]>) => void,
    opts?: AddEventListenerOptions,
  ): () => void {
    const l = fn as EventListener;
    this.addEventListener(type, l, opts);
    return () => this.removeEventListener(type, l, opts);
  }
 
  emit<K extends keyof D & string>(type: K, detail: D[K]) {
    const e = new CustomEvent(type, { detail });
    return this.dispatchEvent(e);
  }
}
 
type TimerEvents = { tick: { n: number }; done: undefined };
 
const timer = new Emitter<TimerEvents>();
const off = timer.on("tick", (e) => e.detail.n.toFixed());
timer.emit("tick", { n: 1 });
// @ts-expect-error: detail must be { n: number }
timer.emit("tick", { n: "1" });
off();

class Tooltip {
  // arrow property: stable reference, `this` bound
  private onKey = (e: KeyboardEvent) => {
    if (e.key === "Escape") this.hide();
  };
  show() {
    document.addEventListener("keydown", this.onKey);
  }
  hide() {
    document.removeEventListener("keydown", this.onKey);
  }
}

function mount(el: HTMLElement): () => void {
  const ac = new AbortController();
  const { signal } = ac;
 
  el.addEventListener("pointerenter", show, { signal });
  el.addEventListener("pointerleave", hide, { signal });
  window.addEventListener("resize", place, { signal });
 
  return () => ac.abort(); // removes all three
}
declare function show(): void;
declare function hide(): void;
declare function place(): void;

const input = document.querySelector("input");
 
// type inferred from HTMLElementEventMap["keydown"]
input?.addEventListener("keydown", (e) => e.key);
 
// the element via a closure: already narrowed
input?.addEventListener("input", () => input.value);
 
// `this` is typed for function handlers, not arrows
input?.addEventListener("change", function () {
  this.value; // this: HTMLInputElement
});
 
// target needs narrowing: it may be a child or a text node
document.addEventListener("input", (e) => {
  if (e.target instanceof HTMLInputElement) {
    e.target.value;
  }
});

// annotate with the concrete event type…
const onKey = (e: KeyboardEvent): void => { e.code; };
 
// …or look it up from the map by name
type Ev<K extends keyof HTMLElementEventMap> =
  HTMLElementEventMap[K];
const onPaste = (e: Ev<"paste">) => e.clipboardData;
 
// typed helper returning an unsubscribe function
function on<K extends keyof HTMLElementEventMap>(
  el: HTMLElement,
  type: K,
  fn: (e: HTMLElementEventMap[K]) => void,
  opts?: AddEventListenerOptions,
): () => void {
  el.addEventListener(type, fn, opts);
  return () => el.removeEventListener(type, fn, opts);
}

type Fn<A extends unknown[]> = (...args: A) => void;
type Timer = ReturnType<typeof setTimeout>;
 
export function debounce<A extends unknown[]>(
  fn: Fn<A>, ms: number,
) {
  let t: Timer | undefined;
  const debounced = (...args: A): void => {
    clearTimeout(t);
    t = setTimeout(() => fn(...args), ms);
  };
  debounced.cancel = () => clearTimeout(t);
  return debounced;
}
 
export function throttle<A extends unknown[]>(
  fn: Fn<A>, ms: number,
): Fn<A> {
  let last = 0;
  let t: Timer | undefined;
  let queued: A | undefined;
  return (...args) => {
    const wait = ms - (Date.now() - last);
    if (wait <= 0) {
      last = Date.now();
      fn(...args);                  // leading call
      return;
    }
    queued = args;
    t ??= setTimeout(() => {
      last = Date.now();
      t = undefined;
      if (queued) fn(...queued);    // trailing call
    }, wait);
  };
}
 
export function rafThrottle<A extends unknown[]>(fn: Fn<A>) {
  let frame = 0;
  let latest: A | undefined;
  return (...args: A): void => {
    latest = args;
    if (frame) return;
    frame = requestAnimationFrame(() => {
      frame = 0;
      if (latest) fn(...latest);
    });
  };
}

import { debounce, rafThrottle } from "./rate-limit";
 
const box = document.querySelector("input[type=search]");
const search = debounce((q: string) => {
  void fetch(`/api/search?q=${encodeURIComponent(q)}`);
}, 300);
 
box?.addEventListener("input", () => {
  if (box instanceof HTMLInputElement) search(box.value);
});
 
const dot = document.querySelector<HTMLElement>(".dot");
window.addEventListener("pointermove", rafThrottle(
  (e: PointerEvent) => {
    dot?.style.setProperty("--x", `${e.clientX}px`);
  },
));