Skip to content

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

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

/**
 * @file listWindow.test.ts
 * @input The fixed-pitch range and anchor calculation
 * @output Range, gap, guard and anchor assertions
 * @position Colocated tests for the private list-windowing module
 */
import {describe, it} from 'vitest';
import assert from 'node:assert/strict';
import {calculateListWindow, reconcileListAnchor} from './listWindow';

const defaults = {
  rowCount: 100,
  rowHeight: 20,
  viewportHeight: 100,
  scrollTop: 0,
  startOffset: 0,
  isMeasured: true,
};
const rows = (plan: NonNullable<ReturnType<typeof calculateListWindow>>) =>
  plan.segments.flatMap(segment =>
    segment.type === 'rows'
      ? Array.from(
          {length: segment.end - segment.start},
          (_, i) => segment.start + i,
        )
      : [],
  );

describe('fixed-pitch list window', () => {
  it('seeds SSR and first-client rows identically without rendering all data', () => {
    const plan = calculateListWindow({
      ...defaults,
      isMeasured: false,
      scrollTop: 800,
    })!;
    assert.deepEqual(rows(plan), [0, 1, 2, 3, 4, 5, 6, 7, 8]);
    assert.deepEqual(plan.segments, [
      {type: 'rows', start: 0, end: 9},
      {type: 'gap', start: 9, end: 100, height: 1820},
    ]);
  });
  it('intersects partial rows, then overscans four per side', () => {
    const plan = calculateListWindow({...defaults, scrollTop: 210})!;
    assert.deepEqual(
      rows(plan),
      Array.from({length: 14}, (_, i) => i + 6),
    );
    assert.equal(plan.firstVisibleIndex, 10);
    assert.equal(plan.offset, 10);
  });
  it('reports the negative distance to the first row while the leading content shows', () => {
    const plan = calculateListWindow({
      ...defaults,
      startOffset: 40,
      scrollTop: 25,
    })!;
    assert.equal(plan.firstVisibleIndex, 0);
    assert.equal(plan.offset, -15);
    assert.equal(
      calculateListWindow({...defaults, startOffset: 40})!.offset,
      -40,
    );
  });
  it('accounts for the start offset and a partly visible list', () => {
    assert.deepEqual(
      rows(calculateListWindow({...defaults, startOffset: 80})!),
      [0, 1, 2, 3, 4],
    );
    assert.deepEqual(
      rows(
        calculateListWindow({...defaults, startOffset: 80, scrollTop: 100})!,
      ),
      [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
    );
  });
  it('retains exactly one high focused row in logical order with truthful gaps', () => {
    const plan = calculateListWindow({
      ...defaults,
      scrollTop: 400,
      focusIndex: 80,
    })!;
    assert.deepEqual(rows(plan), [
      ...Array.from({length: 13}, (_, i) => 16 + i),
      80,
    ]);
    assert.equal(plan.segments.filter(s => s.type === 'gap').length, 3);
    assert.equal(
      plan.segments.reduce(
        (height, s) =>
          height + (s.type === 'gap' ? s.height : (s.end - s.start) * 20),
        0,
      ),
      2000,
    );
    assert.equal(new Set(rows(plan)).size, rows(plan).length);
  });
  it('does not duplicate focus within or adjacent to the ordinary range', () => {
    const plan = calculateListWindow({
      ...defaults,
      scrollTop: 400,
      focusIndex: 28,
    })!;
    assert.equal(plan.segments.filter(s => s.type === 'rows').length, 1);
    assert.deepEqual(
      rows(plan),
      Array.from({length: 13}, (_, i) => 16 + i),
    );
    assert.equal(
      calculateListWindow({
        ...defaults,
        scrollTop: 400,
        focusIndex: 29,
      })!.segments.filter(s => s.type === 'rows').length,
      1,
    );
  });
  it('clamps negative and stale end scrolls and supports fractional pitch', () => {
    assert.deepEqual(
      rows(calculateListWindow({...defaults, scrollTop: -100})!),
      rows(calculateListWindow(defaults)!),
    );
    assert.deepEqual(
      rows(calculateListWindow({...defaults, scrollTop: 1e9})!),
      [91, 92, 93, 94, 95, 96, 97, 98, 99],
    );
    const plan = calculateListWindow({
      ...defaults,
      rowHeight: 12.5,
      viewportHeight: 31.25,
      scrollTop: 131.25,
    })!;
    assert.equal(plan.firstVisibleIndex, 10);
    assert.equal(plan.offset, 6.25);
  });
  it('returns no rows or gaps for an empty list and bounds a short one', () => {
    assert.deepEqual(
      calculateListWindow({...defaults, rowCount: 0})!.segments,
      [],
    );
    assert.deepEqual(
      rows(calculateListWindow({...defaults, rowCount: 3})!),
      [0, 1, 2],
    );
  });
  it('rejects invalid arithmetic rather than compressing or fabricating an engine limit', () => {
    for (const rowHeight of [0, -1, NaN, Infinity, Number.MIN_VALUE]) {
      assert.equal(calculateListWindow({...defaults, rowHeight}), null);
    }
    for (const viewportHeight of [0, -1, NaN, Infinity]) {
      assert.equal(calculateListWindow({...defaults, viewportHeight}), null);
    }
    for (const rowCount of [
      -1,
      0.5,
      NaN,
      Infinity,
      Number.MAX_SAFE_INTEGER + 1,
    ]) {
      assert.equal(calculateListWindow({...defaults, rowCount}), null);
    }
    assert.equal(calculateListWindow({...defaults, scrollTop: NaN}), null);
    assert.equal(
      calculateListWindow({...defaults, startOffset: Infinity}),
      null,
    );
    assert.equal(
      calculateListWindow({...defaults, rowCount: 100, rowHeight: 1e308}),
      null,
    );
    assert.equal(
      calculateListWindow({
        ...defaults,
        rowCount: 1,
        rowHeight: 1e308,
        startOffset: 1e308,
      }),
      null,
    );
    assert.ok(calculateListWindow({...defaults, rowCount: 1e6, rowHeight: 40}));
  });
  it('clamps scrolling to a larger scroll height and rejects an invalid one', () => {
    const base = {...defaults, rowCount: 10, scrollTop: 250};
    const rowsOnly = calculateListWindow(base);
    const withTrailing = calculateListWindow({...base, scrollHeight: 300});
    assert.ok(rowsOnly && withTrailing);
    assert.ok(withTrailing.firstVisibleIndex > rowsOnly.firstVisibleIndex);
    assert.equal(calculateListWindow({...base, scrollHeight: -1}), null);
    assert.equal(
      calculateListWindow({...base, scrollHeight: Number.NaN}),
      null,
    );
  });
  it('preserves ordered coverage, gap extent and mounted bounds across fractional/end cases', () => {
    for (const rowCount of [0, 1, 9, 100, 100000]) {
      for (const rowHeight of [12.5, 20, 48]) {
        for (const viewportHeight of [1, 100, 240, 1000]) {
          for (const scrollTop of [
            0,
            1,
            100,
            rowCount * rowHeight,
            rowCount * rowHeight * 10,
          ]) {
            for (const focusIndex of [
              0,
              Math.floor(rowCount / 2),
              rowCount - 1,
            ]) {
              const plan = calculateListWindow({
                rowCount,
                rowHeight,
                viewportHeight,
                scrollTop,
                startOffset: 37,
                isMeasured: true,
                focusIndex,
              })!;
              const indices = rows(plan);
              assert.equal(new Set(indices).size, indices.length);
              assert.ok(
                indices.every(
                  (value, index) => index === 0 || indices[index - 1] < value,
                ),
              );
              assert.ok(
                indices.length <=
                  Math.ceil(viewportHeight / rowHeight) + 1 + 8 + 1,
              );
              assert.ok(
                plan.segments.filter(segment => segment.type === 'gap')
                  .length <= 3,
              );
              let end = 0;
              let height = 0;
              for (const segment of plan.segments) {
                assert.equal(segment.start, end);
                assert.ok(segment.end > segment.start);
                end = segment.end;
                height +=
                  segment.type === 'gap'
                    ? segment.height
                    : (segment.end - segment.start) * rowHeight;
              }
              assert.equal(end, rowCount);
              assert.equal(height, rowCount * rowHeight);
            }
          }
        }
      }
    }
  });
  it('bounds work at 100k without iterating offscreen rows', () => {
    const plan = calculateListWindow({
      ...defaults,
      rowCount: 100000,
      scrollTop: 1000010,
      focusIndex: 99999,
    })!;
    assert.ok(rows(plan).length <= Math.ceil(100 / 20) + 1 + 8 + 1);
    assert.ok(plan.segments.length <= 5);
  });
});

describe('first-visible-key anchoring', () => {
  const options = {
    previousKeys: ['a', 'b', 'c', 'd'],
    keys: ['x', 'a', 'b', 'c', 'd'],
    firstVisibleIndex: 1,
    offset: 5,
    rowHeight: 20,
    viewportHeight: 20,
    startOffset: 10,
  };
  it('anchors the visible key and fraction, not focus or tail', () => {
    assert.equal(reconcileListAnchor(options), 55);
    assert.equal(
      reconcileListAnchor({...options, keys: ['a', 'b', 'c', 'd', 'e']}),
      35,
    );
  });
  it('chooses surviving successor, predecessor, then start when anchor disappears', () => {
    assert.equal(reconcileListAnchor({...options, keys: ['d', 'c']}), 30);
    assert.equal(reconcileListAnchor({...options, keys: ['a']}), 10);
    // Headroom above the start fallback shows the predecessor is chosen.
    assert.equal(
      reconcileListAnchor({...options, keys: ['z', 'a'], viewportHeight: 1}),
      35,
    );
    assert.equal(reconcileListAnchor({...options, keys: ['x', 'y']}), 10);
  });
  it('preserves canonical number/string distinctions and clamps the new extent', () => {
    assert.equal(
      reconcileListAnchor({
        ...options,
        previousKeys: [0, '0', 1],
        keys: ['0', 0, 1],
        firstVisibleIndex: 1,
      }),
      15,
    );
    assert.equal(
      reconcileListAnchor({...options, keys: ['b'], viewportHeight: 100}),
      0,
    );
  });
  it('keeps a scroll position inside the leading content after rows change', () => {
    const top = {
      ...options,
      previousKeys: ['a', 'b'],
      keys: ['a', 'b', 'c'],
      firstVisibleIndex: 0,
      startOffset: 40,
    };
    assert.equal(reconcileListAnchor({...top, offset: -40}), 0);
    assert.equal(reconcileListAnchor({...top, offset: -15}), 25);
    assert.equal(
      reconcileListAnchor({...top, keys: ['x', 'a', 'b'], offset: -15}),
      45,
    );
  });
  it('keeps a leading-content position when no key survives and sends a row position to the first row', () => {
    const replaced = {
      ...options,
      previousKeys: ['a', 'b'],
      keys: ['x', 'y', 'z'],
      firstVisibleIndex: 0,
      startOffset: 40,
    };
    assert.equal(reconcileListAnchor({...replaced, offset: -40}), 0);
    assert.equal(reconcileListAnchor({...replaced, offset: -15}), 25);
    assert.equal(reconcileListAnchor({...replaced, offset: 10}), 40);
  });
  it('clamps to trailing content and reads a supplied key index', () => {
    const short = {
      ...options,
      previousKeys: ['a', 'b'],
      keys: ['a', 'b'],
      firstVisibleIndex: 1,
    };
    assert.equal(reconcileListAnchor(short), 30);
    assert.equal(
      reconcileListAnchor({...short, trailingContentHeight: 20}),
      35,
    );
    assert.equal(
      reconcileListAnchor({
        ...short,
        trailingContentHeight: 100,
        keyIndices: new Map([['b', 3]]),
      }),
      75,
    );
  });
});