Skip to content

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

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

/**
 * @file useScrollOverflow.test.tsx
 * @input Uses vitest, @testing-library/react, useScrollOverflow
 * @output Unit tests for the hook's measurement, what it observes (the
 *   container's scroll and size, and its content), and its rendered-only gate
 * @position Testing; jsdom lays nothing out, so the scroll box is faked and
 *   `checkVisibility` is stubbed per element.
 */

import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
import {act, renderHook} from '@testing-library/react';
import {useScrollOverflow, useShownScrollOverflow} from './useScrollOverflow';

// jsdom has no ResizeObserver. This one hands the test the shared observer's
// callback so a resize can be delivered on demand; the registration-time
// measurement comes from `observeResize` itself.
let deliverResize: ((entries: ResizeObserverEntry[]) => void) | null = null;

class FakeResizeObserver implements ResizeObserver {
  /** The shared observer, so a test can read what it observes. */
  static last: FakeResizeObserver | null = null;
  constructor(callback: ResizeObserverCallback) {
    FakeResizeObserver.last = this;
    deliverResize = entries => callback(entries, this);
  }
  observe = vi.fn();
  unobserve = vi.fn();
  disconnect = vi.fn();
}

// The shared observer reads only `target` off an entry.
function resizeEntry(target: Element): ResizeObserverEntry {
  return {target} as unknown as ResizeObserverEntry;
}

type Reads = {scrollWidth: number; clientWidth: number; scrollLeft: number};

// Fakes an overflowing scroll box and counts every layout read on it.
function fakeScrollBox(
  el: HTMLElement,
  box: {scrollWidth: number; clientWidth: number; scrollLeft?: number},
): Reads {
  const reads: Reads = {scrollWidth: 0, clientWidth: 0, scrollLeft: 0};
  const values: Reads = {scrollLeft: 0, ...box};
  for (const name of Object.keys(reads) as (keyof Reads)[]) {
    Object.defineProperty(el, name, {
      configurable: true,
      get() {
        reads[name] += 1;
        return values[name];
      },
    });
  }
  return reads;
}

function totalReads(reads: Reads): number {
  return reads.scrollWidth + reads.clientWidth + reads.scrollLeft;
}

function stubRendered(el: HTMLElement, rendered: boolean | undefined) {
  Object.defineProperty(el, 'checkVisibility', {
    configurable: true,
    value: rendered === undefined ? undefined : () => rendered,
  });
}

beforeEach(() => {
  vi.stubGlobal('ResizeObserver', FakeResizeObserver);
});

afterEach(() => {
  vi.unstubAllGlobals();
  vi.restoreAllMocks();
  deliverResize = null;
  FakeResizeObserver.last = null;
});

describe('useScrollOverflow', () => {
  it('measures a rendered container when the ref attaches', () => {
    const el = document.createElement('div');
    const reads = fakeScrollBox(el, {scrollWidth: 600, clientWidth: 300});
    stubRendered(el, true);
    const {result, unmount} = renderHook(() => useScrollOverflow());

    act(() => {
      result.current.scrollRef(el);
    });

    expect(result.current.hasOverflow).toBe(true);
    expect(result.current.overflowStart).toBe(false);
    expect(result.current.overflowEnd).toBe(true);
    expect(totalReads(reads)).toBeGreaterThan(0);
    unmount();
  });

  it('reads no layout while the container is not rendered', () => {
    const el = document.createElement('div');
    const reads = fakeScrollBox(el, {scrollWidth: 600, clientWidth: 300});
    stubRendered(el, false);
    const {result, unmount} = renderHook(() => useScrollOverflow());

    act(() => {
      result.current.scrollRef(el);
    });
    // A resize delivered for the hidden box (a `display: none` or a
    // `content-visibility: hidden` ancestor reports a zero box) is skipped
    // too; a scroll is not (the next case).
    act(() => {
      deliverResize?.([resizeEntry(el)]);
    });

    expect(totalReads(reads)).toBe(0);
    expect(result.current.hasOverflow).toBe(false);
    expect(result.current.overflowEnd).toBe(false);
    unmount();
  });

  it('keeps the last state while hidden and measures again on the reveal', () => {
    const el = document.createElement('div');
    const reads = fakeScrollBox(el, {
      scrollWidth: 600,
      clientWidth: 300,
      scrollLeft: 150,
    });
    stubRendered(el, true);
    const {result, unmount} = renderHook(() => useScrollOverflow());

    act(() => {
      result.current.scrollRef(el);
    });
    expect(result.current.overflowStart).toBe(true);
    expect(result.current.overflowEnd).toBe(true);

    stubRendered(el, false);
    const readsBeforeHide = totalReads(reads);
    act(() => {
      deliverResize?.([resizeEntry(el)]);
    });
    expect(totalReads(reads)).toBe(readsBeforeHide);
    expect(result.current.overflowStart).toBe(true);
    expect(result.current.overflowEnd).toBe(true);

    // Revealed at the end edge with a new size: the resize that follows the
    // reveal measures (a reveal at the same size has no resize, and relies on
    // the scroll having been measured: the next case).
    stubRendered(el, true);
    fakeScrollBox(el, {scrollWidth: 600, clientWidth: 300, scrollLeft: 300});
    act(() => {
      deliverResize?.([resizeEntry(el)]);
    });
    expect(result.current.overflowStart).toBe(true);
    expect(result.current.overflowEnd).toBe(false);
    unmount();
  });

  it('measures a scroll while hidden, so a reveal at the same size is already right', () => {
    const el = document.createElement('div');
    fakeScrollBox(el, {scrollWidth: 600, clientWidth: 300});
    stubRendered(el, true);
    const {result, unmount} = renderHook(() => useScrollOverflow());

    act(() => {
      result.current.scrollRef(el);
    });
    expect(result.current.overflowStart).toBe(false);
    expect(result.current.overflowEnd).toBe(true);

    // Hidden, then scrolled by script to the end edge (a selected tab's
    // reveal under a hidden panel): the scroll is measured.
    stubRendered(el, false);
    const scrolled = fakeScrollBox(el, {
      scrollWidth: 600,
      clientWidth: 300,
      scrollLeft: 300,
    });
    act(() => {
      el.dispatchEvent(new Event('scroll'));
    });
    expect(totalReads(scrolled)).toBeGreaterThan(0);
    expect(result.current.overflowStart).toBe(true);
    expect(result.current.overflowEnd).toBe(false);

    // Revealed at the same size: no resize observation comes, and none is
    // needed.
    stubRendered(el, true);
    expect(result.current.overflowStart).toBe(true);
    expect(result.current.overflowEnd).toBe(false);
    unmount();
  });

  it('measures in a browser without checkVisibility', () => {
    const el = document.createElement('div');
    const reads = fakeScrollBox(el, {scrollWidth: 600, clientWidth: 300});
    stubRendered(el, undefined);
    const {result, unmount} = renderHook(() => useScrollOverflow());

    act(() => {
      result.current.scrollRef(el);
    });

    expect(result.current.hasOverflow).toBe(true);
    expect(totalReads(reads)).toBeGreaterThan(0);
    unmount();
  });

  // The overflow is the content's width against the container's: it changes
  // when the content does, with the container keeping its size.
  it('measures again when a child is added or removed, though the container keeps its size', async () => {
    const el = document.createElement('div');
    fakeScrollBox(el, {scrollWidth: 300, clientWidth: 300});
    stubRendered(el, true);
    const {result, unmount} = renderHook(() => useScrollOverflow());
    act(() => {
      result.current.scrollRef(el);
    });
    expect(result.current.hasOverflow).toBe(false);

    const child = document.createElement('div');
    fakeScrollBox(el, {scrollWidth: 600, clientWidth: 300});
    await act(async () => {
      el.append(child);
    });
    expect(result.current.hasOverflow).toBe(true);

    fakeScrollBox(el, {scrollWidth: 300, clientWidth: 300});
    await act(async () => {
      child.remove();
    });
    expect(result.current.hasOverflow).toBe(false);
    unmount();
  });

  it('measures again when a child resizes, though the container keeps its size', () => {
    const el = document.createElement('div');
    const child = document.createElement('div');
    el.append(child);
    fakeScrollBox(el, {scrollWidth: 300, clientWidth: 300});
    stubRendered(el, true);
    const {result, unmount} = renderHook(() => useScrollOverflow());
    act(() => {
      result.current.scrollRef(el);
    });
    expect(result.current.hasOverflow).toBe(false);

    // The child's content grows past the container.
    fakeScrollBox(el, {scrollWidth: 600, clientWidth: 300});
    act(() => {
      deliverResize?.([resizeEntry(child)]);
    });
    expect(result.current.hasOverflow).toBe(true);
    unmount();
  });

  it("measures again when the container's class or style changes, as a new gap does", async () => {
    const el = document.createElement('div');
    fakeScrollBox(el, {scrollWidth: 300, clientWidth: 300});
    stubRendered(el, true);
    const {result, unmount} = renderHook(() => useScrollOverflow());
    act(() => {
      result.current.scrollRef(el);
    });
    expect(result.current.hasOverflow).toBe(false);

    fakeScrollBox(el, {scrollWidth: 340, clientWidth: 300});
    await act(async () => {
      el.className = 'wider-gap';
    });
    expect(result.current.hasOverflow).toBe(true);

    fakeScrollBox(el, {scrollWidth: 300, clientWidth: 300});
    await act(async () => {
      el.style.columnGap = '0px';
    });
    expect(result.current.hasOverflow).toBe(false);
    unmount();
  });

  it('stops observing the content when the container detaches', () => {
    const el = document.createElement('div');
    const child = document.createElement('div');
    el.append(child);
    fakeScrollBox(el, {scrollWidth: 300, clientWidth: 300});
    stubRendered(el, true);
    const disconnect = vi.spyOn(MutationObserver.prototype, 'disconnect');
    const {result, unmount} = renderHook(() => useScrollOverflow());
    act(() => {
      result.current.scrollRef(el);
    });
    const observer = FakeResizeObserver.last;
    expect(observer?.observe).toHaveBeenCalledWith(child);

    act(() => {
      result.current.scrollRef(null);
    });
    expect(disconnect).toHaveBeenCalled();
    expect(observer?.unobserve).toHaveBeenCalledWith(child);
    expect(observer?.unobserve).toHaveBeenCalledWith(el);
    unmount();
  });

  it('follows a scroll on a rendered container', () => {
    const el = document.createElement('div');
    fakeScrollBox(el, {scrollWidth: 600, clientWidth: 300});
    stubRendered(el, true);
    const {result, unmount} = renderHook(() => useScrollOverflow());

    act(() => {
      result.current.scrollRef(el);
    });
    expect(result.current.overflowStart).toBe(false);

    fakeScrollBox(el, {scrollWidth: 600, clientWidth: 300, scrollLeft: 300});
    act(() => {
      el.dispatchEvent(new Event('scroll'));
    });
    expect(result.current.overflowStart).toBe(true);
    expect(result.current.overflowEnd).toBe(false);
    unmount();
  });

  it('returns the same fields as before, with no way to report a position', () => {
    const {result, unmount} = renderHook(() => useScrollOverflow());
    expect(Object.keys(result.current).sort()).toEqual([
      'hasOverflow',
      'overflowEnd',
      'overflowStart',
      'scrollRef',
    ]);
    unmount();
  });
});

describe('useShownScrollOverflow', () => {
  function attach() {
    const el = document.createElement('div');
    fakeScrollBox(el, {scrollWidth: 600, clientWidth: 300});
    stubRendered(el, true);
    const hook = renderHook(() => useShownScrollOverflow());
    act(() => {
      hook.result.current.scrollRef(el);
    });
    return {el, ...hook};
  }

  const nextFrame = async () =>
    act(
      async () =>
        new Promise<void>(resolve => {
          requestAnimationFrame(() => resolve());
        }),
    );

  it('measures the edges from a reported position while the scroll offset stays put', () => {
    const {result, unmount} = attach();
    expect([result.current.overflowStart, result.current.overflowEnd]).toEqual([
      false,
      true,
    ]);
    act(() => result.current.followShown({offset: 150, travel: 300}));
    expect([result.current.overflowStart, result.current.overflowEnd]).toEqual([
      true,
      true,
    ]);
    act(() => result.current.followShown({offset: 299.5, travel: 300}));
    expect([result.current.overflowStart, result.current.overflowEnd]).toEqual([
      true,
      false,
    ]);
    unmount();
  });

  it('commits an edge change in the report itself, so a held row changes the buttons in its frame', () => {
    const {result, unmount} = attach();
    act(() => {
      result.current.followShown({offset: 150, travel: 300});
      // Rendered before the report returns, not when the batch ends.
      expect(result.current.overflowStart).toBe(true);
    });
    unmount();
  });

  it('renders nothing for a report that changes no edge', () => {
    let renders = 0;
    const el = document.createElement('div');
    fakeScrollBox(el, {scrollWidth: 600, clientWidth: 300});
    stubRendered(el, true);
    const {result, unmount} = renderHook(() => {
      renders += 1;
      return useShownScrollOverflow();
    });
    act(() => {
      result.current.scrollRef(el);
    });
    act(() => result.current.followShown({offset: 150, travel: 300}));
    const before = renders;
    act(() => result.current.followShown({offset: 160, travel: 300}));
    act(() => result.current.followShown({offset: 170, travel: 300}));
    expect(renders).toBe(before);
    unmount();
  });

  it('keeps the reported edges for one frame after null, then measures the scroll offset', async () => {
    const {el, result, unmount} = attach();
    act(() => result.current.followShown({offset: 300, travel: 300}));
    act(() => result.current.followShown(null));
    expect(result.current.overflowEnd).toBe(false);
    // A scroll before that frame still reads the reported position.
    act(() => {
      el.dispatchEvent(new Event('scroll'));
    });
    expect(result.current.overflowEnd).toBe(false);
    await nextFrame();
    expect(result.current.overflowEnd).toBe(true);
    unmount();
  });

  it('leaves no frame running when the container detaches or the hook unmounts', () => {
    const cancel = vi.spyOn(window, 'cancelAnimationFrame');
    const {result, unmount} = attach();
    act(() => result.current.followShown({offset: 300, travel: 300}));
    act(() => result.current.followShown(null));
    const calls = cancel.mock.calls.length;
    act(() => result.current.scrollRef(null));
    expect(cancel.mock.calls.length).toBeGreaterThan(calls);
    // With no container, null schedules nothing.
    const request = vi.spyOn(window, 'requestAnimationFrame');
    act(() => result.current.followShown({offset: 300, travel: 300}));
    act(() => result.current.followShown(null));
    expect(request).not.toHaveBeenCalled();
    unmount();
  });
});