Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
5.4 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file sharedMutationObserver.ts
 * @input MutationObserver API
 * @output Exports observeMutations (one shared observer per set of options),
 *   observeContent, its text-and-children form, and flushMutations
 * @position Internal utility; consumed by useTruncation, hitArea, AppShell's
 *   main-overflow observer, ModalAnnounceProvider's presentation watch and
 *   CheckboxList's required group. The mutation counterpart of sharedResizeObserver:
 *   one observer for every element observed with the same options, so a
 *   repeated cell, row or region does not create one observer per instance.
 */

/**
 * Called once per batch with the records that reached the registration: those
 * whose target is its element or, with `subtree`, one of its descendants.
 * A caller that needs only to know that something changed ignores them.
 */
type MutationCallback = (records: ReadonlyArray<MutationRecord>) => void;

const CONTENT_OPTIONS: MutationObserverInit = {
  characterData: true,
  childList: true,
  subtree: true,
};

interface SharedObserver {
  readonly observer: MutationObserver;
  readonly callbacks: Map<Node, Set<MutationCallback>>;
  readonly deliver: (records: MutationRecord[]) => void;
}

/**
 * One observer per distinct set of options: an observer holds one set of
 * options per node, so registrations that need different options cannot
 * share one.
 */
const observers = new Map<string, SharedObserver>();

function optionsKey(options: MutationObserverInit): string {
  return JSON.stringify([
    options.attributes === true,
    options.attributeFilter == null
      ? null
      : [...options.attributeFilter].sort(),
    options.attributeOldValue === true,
    options.characterData === true,
    options.childList === true,
    options.subtree === true,
  ]);
}

function createSharedObserver(options: MutationObserverInit): SharedObserver {
  const callbacks = new Map<Node, Set<MutationCallback>>();
  const isSubtree = options.subtree === true;
  const deliver = (records: MutationRecord[]) => {
    // One call per callback per batch, however many records it received.
    // With `subtree`, a record's target can be any descendant, so walk up to
    // the observed roots; without it, the target is the observed node.
    const pending = new Map<MutationCallback, MutationRecord[]>();
    for (const record of records) {
      const due = new Set<MutationCallback>();
      if (!isSubtree) {
        callbacks.get(record.target)?.forEach(callback => due.add(callback));
      } else {
        for (
          let node: Node | null = record.target;
          node;
          node = node.parentNode
        ) {
          callbacks.get(node)?.forEach(callback => due.add(callback));
        }
      }
      due.forEach(callback => {
        const received = pending.get(callback);
        if (received) {
          received.push(record);
        } else {
          pending.set(callback, [record]);
        }
      });
    }
    pending.forEach((received, callback) => callback(received));
  };
  return {observer: new MutationObserver(deliver), callbacks, deliver};
}

/**
 * Call `callback` for mutations of `element` matching `options`, through the
 * one observer shared by every registration with the same options. Returns an
 * unsubscribe that removes only this registration.
 *
 * MutationObserver has no per-target unobserve, so a released element stays
 * registered with its shared observer until no element remains; its records
 * match no callback and are ignored. An observer disconnects and is released
 * when its last registration goes.
 */
export function observeMutations(
  element: Node,
  options: MutationObserverInit,
  callback: MutationCallback,
): () => void {
  if (typeof MutationObserver === 'undefined') {
    return () => {};
  }
  const key = optionsKey(options);
  let shared = observers.get(key);
  if (shared == null) {
    shared = createSharedObserver(options);
    observers.set(key, shared);
  }
  const {observer, callbacks} = shared;
  const existing = callbacks.get(element);
  if (existing) {
    existing.add(callback);
  } else {
    callbacks.set(element, new Set([callback]));
    observer.observe(element, options);
  }

  let isSubscribed = true;
  return () => {
    if (!isSubscribed) {
      return;
    }
    isSubscribed = false;
    const targetCallbacks = callbacks.get(element);
    targetCallbacks?.delete(callback);
    if (targetCallbacks?.size === 0) {
      callbacks.delete(element);
    }
    if (callbacks.size === 0 && observers.get(key)?.observer === observer) {
      observer.disconnect();
      observers.delete(key);
    }
  };
}

/**
 * Call `callback` when the element's text or children change (including
 * descendants). Returns an unsubscribe that removes only this registration.
 */
export function observeContent(
  element: Element,
  callback: MutationCallback,
): () => void {
  return observeMutations(element, CONTENT_OPTIONS, callback);
}

/**
 * Deliver at once the records that the shared observer for `options` holds
 * but has not yet delivered. The observer delivers a mutation in a microtask.
 * A read in the same task calls this first to see it.
 */
export function flushMutations(options: MutationObserverInit): void {
  const shared = observers.get(optionsKey(options));
  const records = shared?.observer.takeRecords() ?? [];
  if (shared != null && records.length > 0) {
    shared.deliver(records);
  }
}