Skip to content

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

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

/**
 * @file listWindow.ts
 * @input Fixed CSS-pixel row pitch, scroll geometry and canonical row keys
 * @output Half-open row and gap segments, and first-visible-key reconciliation
 * @position The one private long-list windowing module in Core
 */
export type ListWindowSegment =
  | {type: 'rows'; start: number; end: number}
  | {type: 'gap'; start: number; end: number; height: number};

export interface ListWindowOptions {
  rowCount: number;
  rowHeight: number;
  viewportHeight: number;
  scrollTop: number;
  /** Measured full content extent; does not change the logical row total. */
  scrollHeight?: number;
  /** Distance from the scroll origin to the first row, such as a header. */
  startOffset: number;
  isMeasured: boolean;
  focusIndex?: number;
}

export interface ListWindowPlan {
  segments: ListWindowSegment[];
  start: number;
  end: number;
  firstVisibleIndex: number;
  offset: number;
  totalHeight: number;
}

export function isPositiveFinite(value: number): boolean {
  return Number.isFinite(value) && value > 0;
}

/** Returns null when the inputs cannot form a finite window. */
export function calculateListWindow(
  options: ListWindowOptions,
): ListWindowPlan | null {
  const {
    rowCount,
    rowHeight,
    viewportHeight,
    scrollTop,
    startOffset,
    isMeasured,
    focusIndex,
  } = options;
  const totalHeight = rowCount * rowHeight;
  if (
    !Number.isSafeInteger(rowCount) ||
    rowCount < 0 ||
    !isPositiveFinite(rowHeight) ||
    !isPositiveFinite(viewportHeight) ||
    !Number.isFinite(totalHeight) ||
    !Number.isFinite(startOffset + totalHeight) ||
    !Number.isFinite(viewportHeight / rowHeight) ||
    !Number.isFinite(scrollTop) ||
    (options.scrollHeight !== undefined &&
      (!Number.isFinite(options.scrollHeight) || options.scrollHeight < 0)) ||
    !Number.isFinite(startOffset) ||
    startOffset < 0
  ) {
    return null;
  }
  if (rowCount === 0) {
    return {
      segments: [],
      start: 0,
      end: 0,
      firstVisibleIndex: 0,
      offset: 0,
      totalHeight: 0,
    };
  }

  // Clamp against the full body extent, not mounted DOM or window-local indices.
  const contentHeight = Math.max(
    startOffset + totalHeight,
    options.scrollHeight ?? 0,
  );
  const maximumScroll = Math.max(0, contentHeight - viewportHeight);
  const clampedScroll = Math.min(maximumScroll, Math.max(0, scrollTop));
  const listTop = clampedScroll - startOffset;
  const bodyTop = Math.min(totalHeight, Math.max(0, listTop));
  const bodyBottom = Math.min(
    totalHeight,
    Math.max(0, clampedScroll + viewportHeight - startOffset),
  );
  const firstVisibleIndex = isMeasured
    ? Math.min(rowCount - 1, Math.floor(bodyTop / rowHeight))
    : 0;
  // Above the first row, the offset is the negative distance to it, so an
  // anchor round-trips a scroll position inside the leading content.
  const offset = !isMeasured
    ? 0
    : listTop < 0
      ? listTop
      : bodyTop - firstVisibleIndex * rowHeight;
  const start = isMeasured ? Math.max(0, firstVisibleIndex - 4) : 0;
  const end = isMeasured
    ? Math.min(
        rowCount,
        Math.max(firstVisibleIndex, Math.ceil(bodyBottom / rowHeight)) + 4,
      )
    : Math.min(rowCount, Math.ceil(viewportHeight / rowHeight) + 4);
  return {
    segments: createListWindowSegments(
      rowCount,
      rowHeight,
      start,
      end,
      focusIndex,
    ),
    start,
    end,
    firstVisibleIndex,
    offset,
    totalHeight,
  };
}

/** Mounted rows and gaps for a range, plus one retained row outside it. */
export function createListWindowSegments(
  rowCount: number,
  rowHeight: number,
  start: number,
  end: number,
  focusIndex?: number,
): ListWindowSegment[] {
  if (rowCount === 0) {
    return [];
  }
  const intervals: {start: number; end: number}[] = [{start, end}];
  if (
    focusIndex !== undefined &&
    Number.isInteger(focusIndex) &&
    focusIndex >= 0 &&
    focusIndex < rowCount &&
    (focusIndex < start || focusIndex >= end)
  ) {
    intervals.push({start: focusIndex, end: focusIndex + 1});
    intervals.sort((a, b) => a.start - b.start);
  }
  const merged: {start: number; end: number}[] = [];
  for (const interval of intervals) {
    const previous = merged[merged.length - 1];
    if (previous && interval.start <= previous.end) {
      previous.end = Math.max(previous.end, interval.end);
    } else if (interval.end > interval.start) {
      merged.push({...interval});
    }
  }
  const segments: ListWindowSegment[] = [];
  let cursor = 0;
  for (const interval of merged) {
    if (interval.start > cursor) {
      segments.push({
        type: 'gap',
        start: cursor,
        end: interval.start,
        height: (interval.start - cursor) * rowHeight,
      });
    }
    segments.push({type: 'rows', ...interval});
    cursor = interval.end;
  }
  if (cursor < rowCount) {
    segments.push({
      type: 'gap',
      start: cursor,
      end: rowCount,
      height: (rowCount - cursor) * rowHeight,
    });
  }
  return segments;
}

export interface ListAnchorOptions {
  previousKeys: ReadonlyArray<string | number>;
  keys: ReadonlyArray<string | number>;
  firstVisibleIndex: number;
  offset: number;
  rowHeight: number;
  viewportHeight: number;
  startOffset: number;
  /** Existing non-row content extent retained across logical data changes. */
  trailingContentHeight?: number;
  /** Key-to-index map. Build it when the keys change, never on scroll. */
  keyIndices?: ReadonlyMap<string | number, number>;
}

export function reconcileListAnchor(options: ListAnchorOptions): number {
  const {
    previousKeys,
    keys,
    firstVisibleIndex,
    offset,
    rowHeight,
    viewportHeight,
    startOffset,
  } = options;
  const indices =
    options.keyIndices ?? new Map(keys.map((key, index) => [key, index]));
  let index = indices.get(previousKeys[firstVisibleIndex]);
  if (index === undefined) {
    for (let i = firstVisibleIndex + 1; i < previousKeys.length; i++) {
      index = indices.get(previousKeys[i]);
      if (index !== undefined) {
        break;
      }
    }
  }
  if (index === undefined) {
    for (
      let i = Math.min(firstVisibleIndex - 1, previousKeys.length - 1);
      i >= 0;
      i--
    ) {
      index = indices.get(previousKeys[i]);
      if (index !== undefined) {
        break;
      }
    }
  }
  const maximumScroll = Math.max(
    0,
    startOffset +
      keys.length * rowHeight +
      (options.trailingContentHeight ?? 0) -
      viewportHeight,
  );
  // With no surviving key, a position inside the leading content stays where
  // it is, and a position inside the rows moves to the first row.
  const fraction =
    index === undefined
      ? Math.min(0, Math.max(-startOffset, offset))
      : Math.min(Math.max(-startOffset, offset), rowHeight);
  return Math.min(
    maximumScroll,
    startOffset + (index ?? 0) * rowHeight + fraction,
  );
}