Skip to content

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

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

/** Shared geometry primitives for logical-axis scroll ownership. */

export const SCROLL_OVERFLOW_TOLERANCE = 1;

export type LogicalScrollAxis = 'inline' | 'block';
export type PhysicalScrollAxis = 'x' | 'y';

export interface LogicalAxisMapping {
  inline: PhysicalScrollAxis;
  block: PhysicalScrollAxis;
  inlineReversed: boolean;
  blockReversed: boolean;
}

export interface MeasuredScrollAxisState {
  isScrollable: boolean;
  atStart: boolean;
  atEnd: boolean;
}

export interface LogicalOverflowGeometry {
  inline: boolean;
  block: boolean;
}

const INACTIVE_AXIS_STATE: MeasuredScrollAxisState = {
  isScrollable: false,
  atStart: true,
  atEnd: true,
};

export function getLogicalAxisMapping(
  writingMode: string,
  direction: string,
): LogicalAxisMapping {
  const mode = writingMode.toLowerCase();
  const isVertical = mode.startsWith('vertical') || mode.startsWith('sideways');
  const isRtl = direction === 'rtl';

  if (!isVertical) {
    return {
      inline: 'x',
      block: 'y',
      inlineReversed: isRtl,
      blockReversed: false,
    };
  }

  // sideways-lr runs its natural inline direction from bottom to top. The
  // other vertical/sideways modes run top to bottom; `direction` reverses each.
  const inlineReversed = mode === 'sideways-lr' ? !isRtl : isRtl;
  const blockReversed = mode.endsWith('-rl');

  return {
    inline: 'y',
    block: 'x',
    inlineReversed,
    blockReversed,
  };
}

export function isScrollCapableOverflow(value: string): boolean {
  return value === 'auto' || value === 'scroll' || value === 'overlay';
}

function physicalMetrics(
  element: HTMLElement,
  physicalAxis: PhysicalScrollAxis,
): {
  clientExtent: number;
  contentExtent: number;
  offset: number;
  overflow: string;
} {
  const computedStyle = getComputedStyle(element);
  if (physicalAxis === 'x') {
    return {
      clientExtent: element.clientWidth,
      contentExtent: element.scrollWidth,
      offset: element.scrollLeft,
      overflow: computedStyle.overflowX,
    };
  }
  return {
    clientExtent: element.clientHeight,
    contentExtent: element.scrollHeight,
    offset: element.scrollTop,
    overflow: computedStyle.overflowY,
  };
}

function isMeasurable(
  element: HTMLElement,
  computedStyle: CSSStyleDeclaration,
) {
  return (
    element.isConnected &&
    computedStyle.display !== 'none' &&
    element.clientWidth > 0 &&
    element.clientHeight > 0
  );
}

export function measureLogicalOverflowGeometry(
  element: HTMLElement,
  logicalAxis: LogicalScrollAxis,
  mapping: LogicalAxisMapping,
): boolean | null {
  const computedStyle = getComputedStyle(element);
  if (!isMeasurable(element, computedStyle)) {
    return null;
  }

  const physicalAxis = mapping[logicalAxis];
  const clientExtent =
    physicalAxis === 'x' ? element.clientWidth : element.clientHeight;
  const contentExtent =
    physicalAxis === 'x' ? element.scrollWidth : element.scrollHeight;
  return contentExtent - clientExtent > SCROLL_OVERFLOW_TOLERANCE;
}

export function measureLogicalScrollAxis(
  element: HTMLElement,
  logicalAxis: LogicalScrollAxis,
  mapping: LogicalAxisMapping,
): MeasuredScrollAxisState | null {
  const computedStyle = getComputedStyle(element);
  if (!isMeasurable(element, computedStyle)) {
    return null;
  }

  const physicalAxis = mapping[logicalAxis];
  const metrics = physicalMetrics(element, physicalAxis);
  const maxOffset = metrics.contentExtent - metrics.clientExtent;
  if (
    !isScrollCapableOverflow(metrics.overflow) ||
    maxOffset <= SCROLL_OVERFLOW_TOLERANCE
  ) {
    return INACTIVE_AXIS_STATE;
  }

  return {
    isScrollable: true,
    ...logicalEdges(
      metrics.offset,
      maxOffset,
      mapping[`${logicalAxis}Reversed`],
    ),
  };
}

function logicalEdges(
  offset: number,
  maxOffset: number,
  isReversed: boolean,
): {atStart: boolean; atEnd: boolean} {
  const logicalOffset = Math.min(
    maxOffset,
    Math.max(0, isReversed ? Math.abs(offset) : offset),
  );
  return {
    atStart: logicalOffset <= SCROLL_OVERFLOW_TOLERANCE,
    atEnd: logicalOffset >= maxOffset - SCROLL_OVERFLOW_TOLERANCE,
  };
}

/** Where a scroll left one logical axis, read from geometry alone. */
export interface LogicalScrollPosition {
  /** Content exceeds the viewport by more than the shared tolerance. */
  overflows: boolean;
  atStart: boolean;
  atEnd: boolean;
  /**
   * The offset's sign contradicts the mapping: negative on an axis the
   * mapping reads forward, or positive on one it reads reversed. The writing
   * mode or direction changed without the last full measurement seeing it
   * (a stylesheet alone, for one), so the mapping is stale.
   */
  contradictsMapping: boolean;
}

/**
 * Reads one logical axis after a scroll without reading computed style.
 *
 * A scroll moves the offset and nothing else: the writing-mode mapping and
 * whether the computed overflow can scroll are the ones the last full
 * measurement read, so the caller passes that mapping in. Only box geometry
 * is read here, which costs nothing while layout is clean, as it is during a
 * scroll; a computed-style read would force a style recalculation on every
 * frame of the scroll whenever anything else on the page has dirtied style.
 *
 * Returns null when the viewport is disconnected or has no box (the caller
 * keeps its last valid state, as a full measurement does).
 */
export function measureLogicalScrollPosition(
  element: HTMLElement,
  logicalAxis: LogicalScrollAxis,
  mapping: LogicalAxisMapping,
): LogicalScrollPosition | null {
  if (
    !element.isConnected ||
    element.clientWidth <= 0 ||
    element.clientHeight <= 0
  ) {
    return null;
  }
  const isX = mapping[logicalAxis] === 'x';
  const isReversed = mapping[`${logicalAxis}Reversed`];
  const offset = isX ? element.scrollLeft : element.scrollTop;
  const maxOffset = isX
    ? element.scrollWidth - element.clientWidth
    : element.scrollHeight - element.clientHeight;
  return {
    overflows: maxOffset > SCROLL_OVERFLOW_TOLERANCE,
    ...logicalEdges(offset, maxOffset, isReversed),
    contradictsMapping: isReversed
      ? offset > SCROLL_OVERFLOW_TOLERANCE
      : offset < -SCROLL_OVERFLOW_TOLERANCE,
  };
}