Skip to content

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

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

'use client';

/**
 * @file observeMainOverflow.ts
 * @input A scroll container that holds its content as direct children with
 *   no wrapper: AppShell's main region under `height="fill"`, or a scrolling
 *   LayoutContent, LayoutPanel or StackItem
 * @output observeMainOverflow(main, onChange): reports whether main's content
 *   overflows it on either axis, once at the start and on every change, and
 *   returns the function that stops observing
 * @position Internal and never exported. AppShell makes main a
 *   keyboard stop only while it overflows (`spec:AST-025` FR12,
 *   `component:AppShell` FR4 and PR1). useScrollRegionProps names a
 *   scrolling region only while it overflows. Main has no inner content
 *   box, so its content grows inside it without resizing it: its direct
 *   children's sizes are watched instead.
 *
 * SYNC: When modified, update:
 * - /packages/core/src/AppShell/AppShell.tsx
 * - /packages/core/src/AppShell/observeMainOverflow.test.ts
 * - /packages/core/src/hooks/useScrollRegionProps.ts
 */

import {
  getLogicalAxisMapping,
  measureLogicalScrollAxis,
} from '../hooks/scrollGeometry';
import {observeMutations} from '../utils/sharedMutationObserver';
import {observeResize} from '../utils/sharedResizeObserver';

/**
 * Main's content: layout attributes, text and children, all the way down.
 * One shared observer serves every registration with these options.
 */
const CONTENT_MUTATIONS: MutationObserverInit = {
  attributes: true,
  attributeFilter: ['class', 'dir', 'hidden', 'style'],
  characterData: true,
  childList: true,
  subtree: true,
};

/**
 * Calls `onChange` with whether `main`'s content overflows it on either axis:
 * once with the first measurement, then whenever the answer changes. Signals
 * coalesce into one measurement per frame. A hidden, disconnected or
 * zero-size main is unknown rather than fitting: the last answer stands until
 * a later signal measures it.
 */
export function observeMainOverflow(
  main: HTMLElement,
  onChange: (overflows: boolean) => void,
): () => void {
  let isActive = true;
  let frame: number | null = null;
  let overflows: boolean | null = null;

  const measure = () => {
    frame = null;
    if (!isActive) {
      return;
    }
    const computedStyle = getComputedStyle(main);
    const mapping = getLogicalAxisMapping(
      computedStyle.writingMode,
      computedStyle.direction,
    );
    const inline = measureLogicalScrollAxis(main, 'inline', mapping);
    const block = measureLogicalScrollAxis(main, 'block', mapping);
    if (inline == null || block == null) {
      return;
    }
    const next = inline.isScrollable || block.isScrollable;
    if (next !== overflows) {
      overflows = next;
      onChange(next);
    }
  };

  const scheduleMeasure = () => {
    if (isActive && frame == null) {
      frame = window.requestAnimationFrame(measure);
    }
  };

  // Main keeps its size while its content grows; its children do not. Each
  // direct child's size is watched, following the children as they change.
  const childObservers = new Map<Element, () => void>();
  const syncChildObservers = () => {
    const children = new Set(Array.from(main.children));
    for (const [child, stop] of childObservers) {
      if (!children.has(child)) {
        stop();
        childObservers.delete(child);
      }
    }
    for (const child of children) {
      if (!childObservers.has(child)) {
        childObservers.set(child, observeResize(child, scheduleMeasure));
      }
    }
  };
  const onContentChange = () => {
    syncChildObservers();
    scheduleMeasure();
  };

  measure();
  syncChildObservers();
  const stopObservingMain = observeResize(main, scheduleMeasure);
  const stopObservingContent = observeMutations(
    main,
    CONTENT_MUTATIONS,
    onContentChange,
  );
  window.addEventListener('resize', scheduleMeasure);
  window.visualViewport?.addEventListener('resize', scheduleMeasure);
  main.addEventListener('load', scheduleMeasure, true);
  main.addEventListener('transitionend', scheduleMeasure);
  main.addEventListener('animationend', scheduleMeasure);
  const fonts = document.fonts;
  fonts?.addEventListener?.('loadingdone', scheduleMeasure);
  void fonts?.ready.then(scheduleMeasure);

  return () => {
    isActive = false;
    if (frame != null) {
      window.cancelAnimationFrame(frame);
      frame = null;
    }
    stopObservingMain();
    stopObservingContent();
    for (const stop of childObservers.values()) {
      stop();
    }
    childObservers.clear();
    window.removeEventListener('resize', scheduleMeasure);
    window.visualViewport?.removeEventListener('resize', scheduleMeasure);
    main.removeEventListener('load', scheduleMeasure, true);
    main.removeEventListener('transitionend', scheduleMeasure);
    main.removeEventListener('animationend', scheduleMeasure);
    fonts?.removeEventListener?.('loadingdone', scheduleMeasure);
  };
}