Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

7.9 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright contributors to the kepler.gl project

import test from 'tape';
import {clamp, getNumericRangeMinimum, nextUp} from '@kepler.gl/utils';
import {
  rangesEqual,
  clampRange,
  clampWindowToDomain
} from '../../../src/components/src/common/timeline-helpers';

test('Timeline Zoom Utils -> rangesEqual', t => {
  t.ok(rangesEqual([0, 100], [0, 100]), 'identical ranges should be equal');
  t.ok(rangesEqual([0, 100], [0.5, 99.5]), 'ranges within eps=1 should be equal');
  t.notOk(rangesEqual([0, 100], [2, 100]), 'ranges differing by more than eps should not be equal');
  t.notOk(rangesEqual(null, [0, 100]), 'null first arg should return false');
  t.notOk(rangesEqual([0, 100], null), 'null second arg should return false');
  t.notOk(rangesEqual(null, null), 'both null should return false');
  t.ok(rangesEqual([1000, 5000], [1000, 5000], 0), 'exact match with eps=0');
  t.notOk(rangesEqual([1000, 5000], [1001, 5000], 0), 'off by 1 with eps=0 should not match');
  t.notOk(
    rangesEqual([0, 0.1], [0.02, 0.08], 0),
    'fractional numeric ranges should use exact equality'
  );
  t.notOk(
    rangesEqual([1e12, 1e12 + 0.001], [nextUp(1e12), 1e12 + 0.001], 0),
    'a one-representable-step change at a high offset should stay observable'
  );
  t.end();
});

test('Timeline Zoom Utils -> clampRange', t => {
  t.deepEqual(clampRange([10, 90], [0, 100]), [10, 90], 'range within domain stays unchanged');

  t.deepEqual(
    clampRange([-50, 50], [0, 100]),
    [0, 50],
    'start below domain gets clamped to domain start'
  );

  t.deepEqual(
    clampRange([60, 150], [0, 100]),
    [60, 100],
    'end above domain gets clamped to domain end'
  );

  t.deepEqual(
    clampRange([-50, 200], [0, 100]),
    [0, 100],
    'both out of bounds get clamped to full domain'
  );

  const result = clampRange([80, 70], [0, 100]);
  t.ok(result[1] > result[0], 'inverted range produces valid range with end > start');

  t.end();
});

test('Timeline Zoom Utils -> clampWindowToDomain', t => {
  t.deepEqual(
    clampWindowToDomain(20, 60, [0, 100]),
    [20, 60],
    'window within domain stays unchanged'
  );

  t.deepEqual(
    clampWindowToDomain(-20, 20, [0, 100]),
    [0, 20],
    'window starting before domain gets clamped to start'
  );

  t.deepEqual(
    clampWindowToDomain(80, 120, [0, 100]),
    [80, 100],
    'window ending after domain gets clamped to end'
  );

  const [s, e] = clampWindowToDomain(50, 150, [0, 100]);
  t.ok(s >= 0, 'result start is within domain');
  t.ok(e <= 100, 'result end is within domain');
  t.ok(e > s, 'result end > start');

  t.deepEqual(
    clampWindowToDomain(0, 100, [0, 100]),
    [0, 100],
    'window equal to domain stays unchanged'
  );

  const numericMinimum = getNumericRangeMinimum([0, 0.1]);
  const [numericStart, numericEnd] = clampWindowToDomain(0.05, 0.05, [0, 0.1], numericMinimum);
  t.equal(numericStart, 0.05, 'fractional numeric window keeps its start');
  t.ok(numericEnd > numericStart, 'fractional numeric window gets a representable positive width');
  t.ok(numericEnd < 0.1, 'fractional numeric window does not expand by one whole unit');

  for (const domain of [
    [0, 1e-20],
    [1e12, 1e12 + 0.001]
  ]) {
    const minimum = getNumericRangeMinimum(domain);
    const [start, end] = clampWindowToDomain(domain[0], domain[0], domain, minimum);
    t.ok(end > start, `${domain} should expand a collapsed window by a representable amount`);
    t.ok(end <= domain[1], `${domain} should keep the expanded window inside its domain`);
  }

  t.end();
});

test('Timeline Zoom Utils -> window zoom logic', t => {
  const fullDomain = [0, 1000];
  const filterStart = 200;
  const filterEnd = 400;

  // simulate zoom in (factor > 1)
  const factor = 1.08;
  const center = 300;
  const windowWidth = filterEnd - filterStart;
  const domainWidth = fullDomain[1] - fullDomain[0];
  const minWidth = Math.max(domainWidth / 100, 1);
  const nextWidth = clamp([minWidth, domainWidth], windowWidth / factor);

  t.ok(nextWidth < windowWidth, 'zoom in should reduce window width');
  t.ok(nextWidth >= minWidth, 'zoomed width should not go below minimum');

  // simulate zoom out (factor < 1)
  const factorOut = 1 / 1.08;
  const nextWidthOut = clamp([minWidth, domainWidth], windowWidth / factorOut);
  t.ok(nextWidthOut > windowWidth, 'zoom out should increase window width');
  t.ok(nextWidthOut <= domainWidth, 'zoomed width should not exceed domain');

  t.end();
});

test('Timeline Zoom Utils -> timeline domain zoom logic', t => {
  const fullDomain = [0, 1000];
  const timelineDomain = [200, 800];
  const fullWidth = fullDomain[1] - fullDomain[0];
  const baseWidth = timelineDomain[1] - timelineDomain[0];
  const minWidth = Math.max(fullWidth / 20, 1);

  // zoom in
  const factor = 1.02;
  const nextWidth = clamp([minWidth, fullWidth], baseWidth / factor);
  t.ok(nextWidth < baseWidth, 'zoom in narrows timeline domain');
  t.ok(nextWidth >= minWidth, 'timeline domain width stays above minimum (fullWidth/20)');

  // zoom out
  const factorOut = 1 / 1.02;
  const nextWidthOut = clamp([minWidth, fullWidth], baseWidth / factorOut);
  t.ok(nextWidthOut > baseWidth, 'zoom out widens timeline domain');
  t.ok(nextWidthOut <= fullWidth, 'timeline domain width stays below full width');

  // zoom out from full domain should stay at full
  const nextWidthFull = clamp([minWidth, fullWidth], fullWidth / factorOut);
  t.equal(nextWidthFull, fullWidth, 'cannot zoom out past full domain');

  t.end();
});

test('Timeline Zoom Utils -> fractional numeric zoom uses domain-relative minimums', t => {
  const fullDomain = [0, 0.1];
  const selection = [0.02, 0.08];
  const domainWidth = fullDomain[1] - fullDomain[0];
  const selectionWidth = selection[1] - selection[0];
  const nextSelectionWidth = clamp([domainWidth / 100, domainWidth], selectionWidth / 1.08);
  const nextTimelineWidth = clamp([domainWidth / 20, domainWidth], domainWidth / 1.02);

  t.ok(nextSelectionWidth < selectionWidth, 'fractional selection can zoom below one unit');
  t.ok(nextSelectionWidth > 0, 'fractional selection keeps a positive width');
  t.ok(nextTimelineWidth < domainWidth, 'fractional visible timeline can zoom below one unit');
  t.ok(nextTimelineWidth >= domainWidth / 20, 'fractional timeline respects its relative floor');
  t.end();
});

test('Timeline Zoom Utils -> keyboard panning step logic', t => {
  const filterStart = 200;
  const filterEnd = 400;
  const windowWidth = filterEnd - filterStart;
  const domainRange = [0, 1000];

  // right arrow: new start = filterEnd, new end = filterEnd + windowWidth
  let nextStart = filterEnd;
  let nextEnd = filterEnd + windowWidth;
  [nextStart, nextEnd] = clampWindowToDomain(nextStart, nextEnd, domainRange);
  t.equal(nextStart, 400, 'right arrow: new start equals old end');
  t.equal(nextEnd, 600, 'right arrow: new end equals old end + width');

  // left arrow: new start = filterStart - windowWidth, new end = filterStart
  nextStart = filterStart - windowWidth;
  nextEnd = filterStart;
  [nextStart, nextEnd] = clampWindowToDomain(nextStart, nextEnd, domainRange);
  t.equal(nextStart, 0, 'left arrow: new start equals old start - width');
  t.equal(nextEnd, 200, 'left arrow: new end equals old start');

  // right arrow at domain boundary
  const filterStart2 = 850;
  const filterEnd2 = 1000;
  const windowWidth2 = filterEnd2 - filterStart2;
  nextStart = filterEnd2;
  nextEnd = filterEnd2 + windowWidth2;
  [nextStart, nextEnd] = clampWindowToDomain(nextStart, nextEnd, domainRange);
  t.ok(nextEnd <= 1000, 'clamped end does not exceed domain');
  t.ok(nextStart >= 0, 'clamped start does not go below domain');

  // left arrow at domain boundary
  const filterStart3 = 0;
  const filterEnd3 = 150;
  const windowWidth3 = filterEnd3 - filterStart3;
  nextStart = filterStart3 - windowWidth3;
  nextEnd = filterStart3;
  [nextStart, nextEnd] = clampWindowToDomain(nextStart, nextEnd, domainRange);
  t.equal(nextStart, 0, 'at left boundary, start stays at 0');
  t.ok(nextEnd >= nextStart, 'end stays >= start');

  t.end();
});