Skip to content

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

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

'use client';

/**
 * @file PickerWheel.tsx
 * @input Wheel's props (wheelOptions.ts): options, value and change callback;
 *   optionally a ref for programmatic turns
 * @output PickerWheel: one picker column that moves like UIPickerView
 * @position Internal component; the Wheel under a finger (Wheel.tsx picks it)
 *
 * It moves on the gesture system and the shared animator, not on a native
 * scroller. One strip holds the rows and is the only element that moves.
 *
 * SYNC: When modified, update PickerWheel.test.tsx, Wheel.tsx,
 * DateInputTouch.test.tsx, DateInput.doc.mjs and TimeInput.doc.mjs.
 */

import {
  useCallback,
  useEffect,
  useImperativeHandle,
  useMemo,
  useRef,
  useState,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {scrollTypeOf} from '../gestures/GestureHost';
import {PanGestureRecognizer} from '../gestures/PanGestureRecognizer';
import {TapGestureRecognizer} from '../gestures/TapGestureRecognizer';
import {useGestureRecognizer} from '../gestures/useGestureRecognizer';
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import {rubberBandInverse} from '../motion/rubberBand';
import {resolveMotion} from '../motion/resolveMotion';
import {picker} from '../motion/uikit/picker';
import {registerScrollTable, scroll} from '../motion/uikit/scroll';
import {registerSpringsTable, springs} from '../motion/uikit/springs';
import {
  colorVars,
  fontWeightVars,
  radiusVars,
  spacingVars,
  typeScaleVars,
} from '../theme/tokens.stylex';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
import {lockSelection} from '../gestures/selectionLock';
import {dateInputTouchGeometry, dateInputTouchSizes} from './tokens.stylex';
import {useOwnScrollGesture} from './useOwnScrollGesture';
import {useWheelListbox} from './useWheelListbox';
import {createWheelStrip, type PlayOptions} from './wheelStrip';
import {
  bounceCurve,
  dragOffset,
  nearestIndex,
  offsetBounds,
  planRelease,
  type WheelCurve,
  type WheelLayout,
} from './wheelPhysics';
import {
  canSpinTo,
  endIndex,
  nearestEnabledIndex,
  steppedIndex,
  WHEEL_ROW_HEIGHT,
  type WheelProps,
} from './wheelOptions';

/** Row pitch, px: the touch column keeps the scrolling column's pitch. */
const ROW_HEIGHT = WHEEL_ROW_HEIGHT;
/** UIKit's picker measures scaled to that pitch (UIKit's row is 32 pt). */
const UIKIT_SCALE = ROW_HEIGHT / picker.geometry.rowHeight;
/** UIKit's rubber band dimension for the picker's table, at that pitch. */
const RUBBER_BAND_DIMENSION = picker.geometry.rubberBandDimension * UIKIT_SCALE;

/**
 * The rows' opacity at the column's edges. At 0.7 the row four from the band
 * keeps 5:1 or more in every shipped theme, a margin over WCAG AA's 4.5:1.
 */
const FADE_FLOOR = 0.7;

const styles = stylex.create({
  // The scrolling column's box, band and rows (Wheel.tsx), moved by the
  // gesture system and the compositor instead of a native scroller.
  column: {
    position: 'relative',
    flex: '1 1 0',
    minInlineSize: 0,
    blockSize: dateInputTouchGeometry.paneBlockSize,
    overflow: 'hidden',
    outline: 'none',
    WebkitTapHighlightColor: 'transparent',
  },
  // The rows fade toward the column's edges. A static mask: nothing paints it
  // again as the strip moves. It sits inside the column, so it never clips the
  // column's focus ring.
  fade: {
    position: 'absolute',
    inset: 0,
    pointerEvents: 'none',
    maskImage: `linear-gradient(to bottom, rgb(0 0 0 / ${FADE_FLOOR}), rgb(0 0 0) 50%, rgb(0 0 0 / ${FADE_FLOOR}))`,
  },
  /**
   * The selection band: a centred row-height plate behind the rows.
   * Decorative: the committed value is announced by `aria-selected`.
   */
  band: {
    position: 'absolute',
    insetInline: 0,
    insetBlockStart: `calc(50% - (${dateInputTouchSizes.wheelItemSize} / 2))`,
    blockSize: dateInputTouchSizes.wheelItemSize,
    borderRadius: radiusVars['--radius-element'],
    backgroundColor: colorVars['--color-neutral'],
    pointerEvents: 'none',
  },
  /**
   * The strip holds the rows at their places along the wheel, with its top on
   * the band's row. It moves by minus the wheel's offset, and the animator
   * writes its `translate`. Also what a reduced-motion cross-fade fades.
   */
  strip: {
    position: 'absolute',
    insetInline: 0,
    insetBlockStart: `calc(50% - (${dateInputTouchSizes.wheelItemSize} / 2))`,
    pointerEvents: 'none',
  },
  /** One row: an option at its place along the strip, flat. */
  row: {
    position: 'absolute',
    insetInline: 0,
    blockSize: dateInputTouchSizes.wheelItemSize,
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'center',
    paddingInline: spacingVars['--spacing-2'],
    boxSizing: 'border-box',
    fontSize: typeScaleVars['--text-large-size'],
    fontWeight: fontWeightVars['--font-weight-normal'],
    color: colorVars['--color-text-primary'],
    whiteSpace: 'nowrap',
    overflow: 'hidden',
    textOverflow: 'ellipsis',
    userSelect: 'none',
    // The mark has no transition, unlike the scrolling column's. A colour or
    // weight that animates lays out and paints every frame on the main thread.
    // A mark set as a drag lets go would do so through the coast.
  },
  /** The row under the band, as the scrolling column marks it. */
  rowActive: {
    color: colorVars['--color-text-accent'],
    fontWeight: fontWeightVars['--font-weight-semibold'],
  },
  rowDisabled: {
    color: colorVars['--color-text-disabled'],
  },
  /** A row at its place along the strip. */
  rowAt: (top: string) => ({insetBlockStart: top}),
});

/**
 * The motion tables the wheel resolves its springs from: the scroll bounce
 * and the shared springs. The spring rows register as their module loads,
 * but the scroll table does not. Each register is idempotent, so the wheel
 * calls this right before it resolves a role.
 */
function registerWheelTables(): void {
  registerScrollTable();
  registerSpringsTable();
}

/**
 * A turn onto `to` that a tap, a key or the program starts. The wheel's main
 * interaction is a gesture, so every turn springs.
 */
function turnCurve(
  column: Element | null,
  from: number,
  to: number,
): WheelCurve {
  registerWheelTables();
  return bounceCurve(
    from,
    0,
    to,
    UIKIT_SCALE,
    resolveMotion(column, springs.settle),
  );
}

interface DragState {
  /** The finger's offset at the pan's start, before any rubber band. */
  readonly start: number;
}

/**
 * One UIPickerView column: the Wheel under a finger. It does not scroll
 * natively. WebKit gives every scroll-snapping scroller the fast deceleration
 * rate, and a scroller's momentum cannot be caught or measured. A busy main
 * thread does not stop or jump a motion here. Under Reduce Motion a throw's
 * momentum still plays, as iOS scrolling does. Every other motion
 * cross-fades onto its row.
 *
 * @example
 * ```
 * <PickerWheel label="Month" options={monthOptions} value={month} onChange={setMonth} />
 * ```
 */
export function PickerWheel({
  label,
  options,
  value,
  onChange,
  isActive = true,
  ref,
}: WheelProps) {
  const columnRef = useRef<HTMLDivElement | null>(null);
  const rowsRef = useRef<HTMLDivElement | null>(null);
  const rowCount = options.length;
  const layout = useMemo<WheelLayout>(
    () => ({rowHeight: ROW_HEIGHT, rowCount}),
    [rowCount],
  );
  const [motion] = useState(() => createWheelStrip(layout));
  const selectedIndex = Math.max(
    0,
    options.findIndex(option => option.value === value),
  );
  const dragRef = useRef<DragState | null>(null);
  /** A finger landed on a moving wheel and stopped it. */
  const caughtRef = useRef(false);

  // The latest props, for the motion's and the gesture listeners' callbacks,
  // which are attached once and outlive a render.
  const latestRef = useRef({options, value, onChange, layout});
  useIsomorphicLayoutEffect(() => {
    latestRef.current = {options, value, onChange, layout};
  });

  // The row under the band is marked as the scrolling column marks it. At rest
  // that is the committed row, styled in render. While a finger drags the
  // wheel, the row reaching the band is painted directly, so marking it never
  // re-renders. A motion unmarks every row as it starts and marks the row it
  // stops or ends on. The compositor then plays it with no layout or paint per
  // frame, and no mark rides away from the band.
  const paintedRef = useRef<Set<HTMLElement>>(new Set());
  const paintRow = useCallback((position: number | null) => {
    const container = rowsRef.current;
    if (container == null || container.children.length === 0) {
      return;
    }
    const rows = container.children;
    const {options: currentOptions, value: currentValue} = latestRef.current;
    const active =
      position == null
        ? null
        : ((rows[position] as HTMLElement | undefined) ?? null);
    const painted = paintedRef.current;
    for (const row of painted) {
      row.style.removeProperty('color');
      row.style.removeProperty('font-weight');
    }
    painted.clear();
    const selected = currentOptions.findIndex(
      option => option.value === currentValue,
    );
    if (rows[selected] != null && rows[selected] !== active) {
      // The committed row's own mark gives way while another row is under
      // the band.
      const row = rows[selected] as HTMLElement;
      row.style.color = currentOptions[selected]?.isDisabled
        ? colorVars['--color-text-disabled']
        : colorVars['--color-text-primary'];
      row.style.fontWeight = fontWeightVars['--font-weight-normal'];
      painted.add(row);
    }
    if (active == null || position == null) {
      return;
    }
    active.style.color = currentOptions[position]?.isDisabled
      ? colorVars['--color-text-disabled']
      : colorVars['--color-text-accent'];
    active.style.fontWeight = fontWeightVars['--font-weight-semibold'];
    painted.add(active);
  }, []);

  // Every motion the wheel starts. Under Reduce Motion a transition lands
  // without travel: the animator cross-fades the strip onto its row. The
  // momentum that continues a throw is not a transition, so it plays as is.
  const move = useCallback(
    (curve: WheelCurve, options: PlayOptions = {}) => {
      paintRow(null);
      // The mark comes back from the row the motion reports nearest when it
      // ends, even the row it began on.
      motion.forgetNearest();
      motion.play(curve, options);
    },
    [motion, paintRow],
  );

  // The wheel came to rest at `offset`: commit, or turn on to the row the
  // rest rule names first.
  const arrive = useCallback(
    (offset: number) => {
      const current = latestRef.current;
      const row = nearestIndex(offset, current.layout);
      const committed = current.options.findIndex(
        option => option.value === current.value,
      );
      // A rest on the committed row is not a stop to correct. A committed value
      // outside the bounds stays until a person moves the wheel off it, as in
      // the scrolling column.
      let step = 0;
      if (row !== committed) {
        step =
          nearestEnabledIndex(current.options, row, Math.max(0, committed)) -
          row;
      }
      if (step !== 0) {
        const target = row + step;
        move(turnCurve(columnRef.current, offset, target * ROW_HEIGHT), {
          onEnd: (outcome, end) => {
            if (outcome === 'arrived') {
              arrive(end);
            }
          },
        });
        return;
      }
      const option = current.options[row];
      if (
        option != null &&
        !option.isDisabled &&
        option.value !== current.value
      ) {
        current.onChange(option.value);
      }
    },
    [move],
  );

  const onEnd = useCallback(
    (outcome: 'arrived' | 'stopped', offset: number) => {
      if (outcome === 'arrived') {
        arrive(offset);
      }
    },
    [arrive],
  );

  // The animator holds the strip while it is attached, and lets it go as it
  // detaches or is replaced.
  const attachStrip = useCallback(
    (strip: HTMLDivElement) => {
      rowsRef.current = strip;
      motion.attach(strip);
      return () => {
        rowsRef.current = null;
        motion.attach(null);
      };
    },
    [motion],
  );

  // The motion's layout follows the rows.
  useIsomorphicLayoutEffect(() => {
    motion.setLayout(layout);
  }, [motion, layout]);

  // The band's mark follows the row the motion reports nearest the band.
  useIsomorphicLayoutEffect(() => {
    motion.onNearestChange(paintRow);
    return () => motion.onNearestChange(null);
  }, [motion, paintRow]);
  // At rest on the committed row, render's own mark takes over again.
  useIsomorphicLayoutEffect(() => {
    if (
      motion.isMoving() ||
      dragRef.current != null ||
      nearestIndex(motion.offset(), layout) !== selectedIndex
    ) {
      return;
    }
    for (const row of paintedRef.current) {
      row.style.removeProperty('color');
      row.style.removeProperty('font-weight');
    }
    paintedRef.current.clear();
  });

  // The motion's animations and timers end with the wheel.
  useEffect(() => () => motion.dispose(), [motion]);

  // Park the committed row under the band when the wheel is shown, at once. A
  // value that changes from outside while the wheel is shown turns the wheel
  // onto its row instead. UIDatePicker turns onto its maximum the same way, and
  // never jumps there. For example, a bound clamps the time after another wheel
  // turned, or the calendar moved to another month. A second change during that
  // turn turns on from where the wheel is drawn. Never while a finger or a
  // motion of its own owns the wheel.
  const parkedRef = useRef(false);
  const parkTurnRef = useRef<object | null>(null);
  useIsomorphicLayoutEffect(() => {
    if (!isActive) {
      parkedRef.current = false;
      return;
    }
    if (
      dragRef.current != null ||
      (motion.isMoving() && parkTurnRef.current == null)
    ) {
      return;
    }
    const target = selectedIndex * ROW_HEIGHT;
    const shown = motion.isMoving() ? motion.stop() : motion.offset();
    const isAway = Math.abs(shown - target) > 0.01;
    if (isAway && parkedRef.current) {
      // The turn's own end paints the band's row.
      const turn = {};
      parkTurnRef.current = turn;
      move(turnCurve(columnRef.current, shown, target), {
        onEnd: () => {
          if (parkTurnRef.current === turn) {
            parkTurnRef.current = null;
          }
        },
      });
      return;
    }
    if (isAway) {
      motion.setOffset(target);
    }
    parkedRef.current = true;
  }, [isActive, selectedIndex, motion, move]);

  // A hidden wheel keeps no motion running and holds no drag. Hiding it
  // mid-drag ends the pan without calling its listener, because the toggle's
  // owner owns that end. So the drag is dropped here, uncommitted. Shown again,
  // the wheel parks the committed row.
  useEffect(() => {
    if (!isActive) {
      dragRef.current = null;
      motion.stop();
    }
  }, [isActive, motion]);

  // A finger lands: a moving wheel stops where it is on screen.
  const onTouchDown = useCallback(
    (time: number) => {
      caughtRef.current = motion.isMoving();
      if (caughtRef.current) {
        motion.stop(time);
      }
    },
    [motion],
  );

  // The latest touch-down handler, for the gesture listener attached once.
  const onTouchDownRef = useRef(onTouchDown);
  useIsomorphicLayoutEffect(() => {
    onTouchDownRef.current = onTouchDown;
  });

  const release = useCallback(
    (velocity: number) => {
      registerWheelTables();
      const plan = planRelease(
        motion.offset(),
        velocity,
        latestRef.current.layout,
        resolveMotion(columnRef.current, scroll.bounce),
      );
      move(plan.curve, {
        ticks: true,
        onEnd,
        touchRelease: true,
        momentum: plan.kind === 'coast' || plan.kind === 'edge',
      });
    },
    [motion, move, onEnd],
  );

  const pan = useGestureRecognizer(
    columnRef,
    () =>
      new PanGestureRecognizer({
        name: 'wheel-pan',
        direction: 'vertical',
        // A trackpad's two-finger scroll drives the pan as a finger does. The
        // rows follow, coast on at the lift with the fingers' last speed, and
        // rest by the rest rule. A mouse wheel's notches never reach the pan.
        allowedScrollTypes: ['continuous'],
        // A held finger on the wheel never starts text selection or the
        // callout.
        selectionLock: lockSelection,
        shouldReceiveTouch: (_pan, touch) => {
          onTouchDownRef.current(touch.time);
          return true;
        },
      }),
    recognizer => {
      const {layout: currentLayout} = latestRef.current;
      switch (recognizer.state) {
        case 'began': {
          const shown = motion.isMoving() ? motion.stop() : motion.offset();
          dragRef.current = {start: fingerOffset(shown, currentLayout)};
          motion.resetDrag();
          motion.setOffset(
            dragOffset(
              dragRef.current.start - recognizer.translation().y,
              currentLayout,
            ),
            {ticks: true},
          );
          break;
        }
        case 'changed': {
          const drag = dragRef.current;
          if (drag == null) {
            break;
          }
          motion.setOffset(
            dragOffset(drag.start - recognizer.translation().y, currentLayout),
            {ticks: true},
          );
          break;
        }
        case 'ended': {
          const drag = dragRef.current;
          dragRef.current = null;
          // A scroll view's release velocity (the pan's last two, blended as
          // UIPickerView's); the rows move against the finger.
          release(drag == null ? 0 : -recognizer.scrollVelocity().y);
          break;
        }
        case 'cancelled': {
          dragRef.current = null;
          release(0);
          break;
        }
        case 'possible':
        case 'failed':
          break;
      }
    },
    {isEnabled: isActive},
  );

  // A touch that stopped a moving wheel and lifted without dragging: the
  // wheel eases onto the nearest row, as a release without velocity does.
  useEffect(
    () =>
      pan.addTransitionListener((_pan, _from, to) => {
        // The flag stays up until the next touch lands. The tap recognizer may
        // hear of this lift after the pan does, and must not read it as a tap
        // on a row.
        if (to === 'failed' && caughtRef.current && !motion.isMoving()) {
          release(0);
        }
      }),
    [pan, motion, release],
  );

  useGestureRecognizer(
    columnRef,
    () => new TapGestureRecognizer({name: 'wheel-tap'}),
    recognizer => {
      if (recognizer.state !== 'ended' || caughtRef.current) {
        return;
      }
      const column = columnRef.current;
      if (column == null) {
        return;
      }
      const box = column.getBoundingClientRect();
      const {y} = recognizer.location();
      const offset = motion.offset();
      const currentLayout = latestRef.current.layout;
      const target = rowAtPoint(
        y - (box.top + box.height / 2),
        offset,
        currentLayout,
      );
      if (target == null || target === nearestIndex(offset, currentLayout)) {
        return;
      }
      move(turnCurve(columnRef.current, offset, target * ROW_HEIGHT), {
        onEnd,
      });
    },
    {isEnabled: isActive},
  );

  // Keep the finger, and the pointer it lands with: inside a BottomSheet the
  // sheet would otherwise read a downward drag here as swipe-to-dismiss. This
  // wheel pans through the gesture system, which never cancels the pointer
  // the sheet armed on (see useOwnScrollGesture).
  useOwnScrollGesture(columnRef, 'all', {
    isEnabled: isActive,
    isPointerKept: true,
  });

  // A spin turns only onto an enabled row (canSpinTo). So its arrival commits
  // that row, and nothing turns on past it. It reports the row it was asked
  // for, as the scrolling column does.
  const spinTo = useCallback(
    async (index: number): Promise<boolean> =>
      new Promise(resolve => {
        if (!canSpinTo(latestRef.current.options, index)) {
          resolve(false);
          return;
        }
        const offset = motion.offset();
        move(turnCurve(columnRef.current, offset, index * ROW_HEIGHT), {
          onEnd: (outcome, end) => {
            if (outcome === 'arrived') {
              arrive(end);
            }
            resolve(outcome === 'arrived');
          },
        });
      }),
    [motion, move, arrive],
  );

  useImperativeHandle(ref, () => ({spinTo}), [spinTo]);

  const turnToPosition = useCallback(
    (position: number, offset: number) => {
      const current = latestRef.current;
      const option = current.options[position];
      if (option.value !== current.value) {
        current.onChange(option.value);
      }
      move(turnCurve(columnRef.current, offset, position * ROW_HEIGHT));
    },
    [move],
  );

  const moveBy = useCallback(
    (delta: number) => {
      const current = latestRef.current;
      if (current.options.length === 0 || delta === 0) {
        return;
      }
      // Keys step from the row the wheel is heading to, not the one it is
      // passing: two quick presses move two rows. A key with nowhere to go
      // leaves a turn in flight to finish on its row.
      const row = steppedIndex(
        current.options,
        nearestIndex(motion.target(), current.layout),
        delta,
      );
      if (row == null) {
        return;
      }
      const offset = motion.isMoving() ? motion.stop() : motion.offset();
      turnToPosition(row, offset);
    },
    [motion, turnToPosition],
  );

  // A mouse wheel's notch turns the wheel one row, as an arrow key does, with
  // no coast. The gesture host leaves a notch to what is under the pointer,
  // which is this wheel. A wheel the pan took arrives here already prevented.
  // A ctrl-wheel stays the page's zoom, and a sideways scroll stays the
  // page's.
  useEffect(() => {
    const column = columnRef.current;
    if (column == null || !isActive) {
      return undefined;
    }
    const onWheel = (event: WheelEvent) => {
      if (
        event.defaultPrevented ||
        event.ctrlKey ||
        event.shiftKey ||
        event.deltaY === 0 ||
        Math.abs(event.deltaX) > Math.abs(event.deltaY) ||
        scrollTypeOf(event) !== 'discrete'
      ) {
        return;
      }
      event.preventDefault();
      moveBy(Math.sign(event.deltaY));
    };
    column.addEventListener('wheel', onWheel, {passive: false});
    return () => column.removeEventListener('wheel', onWheel);
  }, [isActive, moveBy]);

  // Home and End: the first and the last enabled row.
  const moveToEnd = useCallback(
    (end: 'first' | 'last') => {
      const row = endIndex(latestRef.current.options, end);
      if (row == null) {
        return;
      }
      const offset = motion.isMoving() ? motion.stop() : motion.offset();
      turnToPosition(row, offset);
    },
    [motion, turnToPosition],
  );

  // A click on a row commits it at once and turns the wheel there, as the arrow
  // keys do. The click comes from assistive technology, a keyboard, a test, or
  // a mouse the tap recognizer did not take. A finger's tap is the tap
  // recognizer's, and the click it would produce is swallowed by the gesture
  // system.
  const activateRow = useCallback(
    (row: number) => {
      const current = latestRef.current;
      const option = current.options[row];
      if (option == null || option.isDisabled) {
        return;
      }
      const offset = motion.isMoving() ? motion.stop() : motion.offset();
      if (option.value !== current.value) {
        current.onChange(option.value);
      }
      move(turnCurve(columnRef.current, offset, row * ROW_HEIGHT));
    },
    [motion, move],
  );

  const {listboxProps, optionProps} = useWheelListbox({
    label,
    options,
    value,
    // The committed row: a value set from outside shows in the same render.
    activeIndex: selectedIndex,
    stepBy: moveBy,
    toEnd: moveToEnd,
    activate: activateRow,
  });

  return (
    <div
      ref={columnRef}
      {...listboxProps}
      data-wheel=""
      {...stylex.props(styles.column, focusOutlineStyles.focusVisible)}>
      <div data-wheel-fade="" {...stylex.props(styles.fade)}>
        <div aria-hidden="true" {...stylex.props(styles.band)} />
        <div
          ref={attachStrip}
          data-wheel-strip=""
          {...stylex.props(styles.strip)}>
          {options.map((option, index) => (
            <div
              key={option.value}
              {...optionProps(option, index)}
              data-wheel-row=""
              data-label={option.label}
              {...stylex.props(
                styles.row,
                styles.rowAt(`${index * ROW_HEIGHT}px`),
                index === selectedIndex && styles.rowActive,
                option.isDisabled && styles.rowDisabled,
              )}>
              {option.label}
            </div>
          ))}
        </div>
      </div>
    </div>
  );
}

PickerWheel.displayName = 'PickerWheel';

/**
 * The row under a point `dy` px below the band's centre, or null past either
 * end of the list.
 */
function rowAtPoint(
  dy: number,
  offset: number,
  layout: WheelLayout,
): number | null {
  const position = Math.round((offset + dy) / layout.rowHeight);
  if (position < 0 || position >= layout.rowCount) {
    return null;
  }
  return position;
}

/**
 * The finger's offset for a shown one. Past an end, it is the travel that the
 * rubber band shows as `shown`. So a drag that starts in a bounce continues
 * without a jump.
 */
function fingerOffset(shown: number, layout: WheelLayout): number {
  const {min, max} = offsetBounds(layout);
  const dimension = RUBBER_BAND_DIMENSION;
  if (shown < min) {
    return min + rubberBandInverse(shown - min, dimension);
  }
  if (shown > max) {
    return max + rubberBandInverse(shown - max, dimension);
  }
  return shown;
}