@carto/kepler.gl 0.0.1-alpha.map-libre

package/src/utils/observe-dimensions.js

@@ -0,0 +1,115 @@
+// Copyright (c) 2022 Uber Technologies, Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+import throttle from 'lodash.throttle';
+import {useEffect, useRef, useState} from 'react';
+import ResizeObserver from 'resize-observer-polyfill';
+
+const DEFAULT_THROTTLE_DELAY = 100;
+
+// Using a single ResizeObserver for all elements can be 10x
+// more performant than using a separate ResizeObserver per element
+// https://groups.google.com/a/chromium.org/forum/#!msg/blink-dev/z6ienONUb5A/F5-VcUZtBAAJ
+let _observerRegistry;
+
+function getObserverRegistry() {
+  if (_observerRegistry === undefined) {
+    const callbacks = new Map();
+    const resizeObserver = new ResizeObserver((entries, observer) => {
+      for (const entry of entries) {
+        callbacks.get(entry.target)?.(entry, observer);
+      }
+    });
+    _observerRegistry = {
+      subscribe(target, callback) {
+        resizeObserver.observe(target);
+        callbacks.set(target, callback);
+      },
+      unsubscribe(target) {
+        resizeObserver.unobserve(target);
+        callbacks.delete(target);
+      }
+    };
+  }
+  return _observerRegistry;
+}
+
+export function observeDimensions(target, handleResize, throttleDelay = DEFAULT_THROTTLE_DELAY) {
+  const registry = getObserverRegistry();
+  const handler = throttleDelay > 0 ? throttle(handleResize, throttleDelay) : handleResize;
+  registry.subscribe(target, entry => handler(getSize(target, entry)));
+}
+
+export function unobserveDimensions(target) {
+  const registry = getObserverRegistry();
+  registry.unsubscribe(target);
+}
+
+function getSize(node, entry) {
+  if (entry.contentRect) {
+    const {width, height} = entry.contentRect;
+    return {width, height};
+  }
+  if (node.getBoundingClientRect) {
+    const {width, height} = node.getBoundingClientRect();
+    return {width, height};
+  }
+  return null;
+}
+
+/**
+ * Usage example:
+ * const [ref, dimensions] = useDimensions<HTMLDivElement>();
+ *
+ * @param throttleDelay
+ * @returns {[React.RefObject<Element>, {width: number, height: number} | null]}
+ */
+export default function useDimensions(throttleDelay = DEFAULT_THROTTLE_DELAY) {
+  const ref = useRef(null);
+  const [size, setSize] = useState(null);
+
+  useEffect(() => {
+    const {current} = ref;
+    if (!current) {
+      return;
+    }
+
+    let didUnobserve = false;
+    observeDimensions(
+      current,
+      entry => {
+        if (didUnobserve) return;
+        const newSize = getSize(current, entry);
+        if (newSize) {
+          // @ts-ignore
+          setSize(newSize);
+        }
+      },
+      throttleDelay
+    );
+    return () => {
+      didUnobserve = true;
+      unobserveDimensions(current);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [throttleDelay]);
+
+  return [ref, size];
+}

package/src/utils/projection-utils.js

@@ -0,0 +1,72 @@
+// Copyright (c) 2022 Uber Technologies, Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+import geoViewport from '@mapbox/geo-viewport';
+import Console from 'global/console';
+
+const MAPBOX_TILE_SIZE = 512;
+
+function isLat(num) {
+  return Number.isFinite(num) && num <= 90 && num >= -90;
+}
+function isLng(num) {
+  return Number.isFinite(num) && num <= 180 && num >= -180;
+}
+
+/**
+ * bounds should be [minLng, minLat, maxLng, maxLat]
+ * @param {*} bounds
+ */
+export function validateBounds(bounds) {
+  // array: [ -180, -85.05112877980659, 180, 85.0511287798066 ]
+  // validate bounds
+  if (
+    Array.isArray(bounds) &&
+    bounds.length === 4 &&
+    [bounds[0], bounds[2]].every(isLng) &&
+    [bounds[1], bounds[3]].every(isLat)
+  ) {
+    return bounds;
+  }
+  return null;
+}
+
+export function getCenterAndZoomFromBounds(bounds, {width, height}) {
+  const validBounds = validateBounds(bounds);
+  if (!validBounds) {
+    Console.warn('invalid map bounds provided');
+    return null;
+  }
+
+  // viewport(bounds, dimensions, minzoom, maxzoom, tileSize, allowFloat)
+  const {zoom} = geoViewport.viewport(
+    bounds,
+    [width, height],
+    undefined,
+    undefined,
+    MAPBOX_TILE_SIZE
+  );
+  // center being calculated by geo-vieweport.viewport has a complex logic that
+  // projects and then unprojects the coordinates to determine the center
+  // Calculating a simple average instead as that is the expected behavior in most of cases
+  const center = [(bounds[0] + bounds[2]) / 2, (bounds[1] + bounds[3]) / 2];
+
+  return {zoom, center};
+}

package/src/utils/searcher-utils.js

@@ -0,0 +1,37 @@
+// Copyright (c) 2022 Uber Technologies, Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+/* eslint-disable callback-return */
+export function simpleSearcher(autofillValues, page, query, cb) {
+  var regex = new RegExp(query, 'i');
+  var foundQuery = false;
+  var matches = (autofillValues || []).filter(function _filter(item) {
+    var tag = item.name;
+    foundQuery = foundQuery || tag === query;
+    return tag && regex.test(tag);
+  });
+
+  if (cb) {
+    cb(matches);
+  }
+
+  return matches;
+}
+/* eslint-enable callback-return */

package/src/utils/split-map-utils.js

@@ -0,0 +1,104 @@
+// Copyright (c) 2022 Uber Technologies, Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+import cloneDeep from 'lodash.clonedeep';
+
+/**
+ * Add new layers to both existing maps
+ * @param {Object} splitMaps
+ * @param {Object|Array<Object>} layers
+ * @returns {Array<Object>} new splitMaps
+ */
+export function addNewLayersToSplitMap(splitMaps, layers) {
+  const newLayers = Array.isArray(layers) ? layers : [layers];
+
+  if (!splitMaps.length || !newLayers.length) {
+    return splitMaps;
+  }
+
+  // add new layer to both maps,
+  // don't override, if layer.id is already in splitMaps
+  return splitMaps.map(settings => ({
+    ...settings,
+    layers: {
+      ...settings.layers,
+      ...newLayers.reduce(
+        (accu, newLayer) =>
+          // @ts-ignore
+          newLayer.id in settings.layers || !newLayer.config.isVisible
+            ? accu
+            : {
+                ...accu,
+                [newLayer.id]: newLayer.config.isVisible
+              },
+        {}
+      )
+    }
+  }));
+}
+
+/**
+ * Remove an existing layer from split map settings
+ * @param {Object} splitMaps
+ * @param {Object} layer
+ * @returns {Object} Maps of custom layer objects
+ */
+export function removeLayerFromSplitMaps(splitMaps, layer) {
+  if (!splitMaps.length) {
+    return splitMaps;
+  }
+  return splitMaps.map(settings => {
+    // eslint-disable-next-line no-unused-vars
+    const {[layer.id]: _, ...newLayers} = settings.layers;
+    return {
+      ...settings,
+      layers: newLayers
+    };
+  });
+}
+
+/**
+ * This method will compute the default maps layer settings
+ * based on the current layers visibility
+ * @param {Array<Object>} layers
+ * @returns {Array<Object>} layer visibility for each panel
+ */
+export function getInitialMapLayersForSplitMap(layers) {
+  return layers
+    .filter(layer => layer.config.isVisible)
+    .reduce(
+      (newLayers, currentLayer) => ({
+        ...newLayers,
+        [currentLayer.id]: currentLayer.config.isVisible
+      }),
+      {}
+    );
+}
+
+/**
+ * This method will get default splitMap settings based on existing layers
+ * @param {Array<Object>} layers
+ * @returns {Array<Object>} split map settings
+ */
+export function computeSplitMapLayers(layers) {
+  const mapLayers = getInitialMapLayersForSplitMap(layers);
+
+  return [{layers: mapLayers}, {layers: cloneDeep(mapLayers)}];
+}

package/src/utils/table-utils/UPGRADE-data-container.md

@@ -0,0 +1,38 @@
+# Upgrade Guide (Data Containers)
+
+### Major changes
+- `KeplerTable.allData: any[][]` is substituted with `KeplerTable.dataContainer: DataContainerInterface`.
+
+### Step by step upgrade
+| File | Function | Change |
+| ---- | --- | --- |
+| base-layer.js & extended layers | accessors | Accessors in default Kepler layers now expect a data container as one of parameters: ```const pointPosAccessor = config => dc => d => {return ...}``` where `dc` is an instance of `DataContainerInterface`, and `d` is an object that is expected to contain an index of a row in the data container. | 
+|            | updateLayerMeta() | 1st parameter has to be an instance of `DataContainerInterface`. |
+|            | getPointsBounds() | 1st parameter has to be an instance of `DataContainerInterface`. |
+|            | calculateDataAttribute() | 1st parameter has to be an instance of `KeplerTable`. |
+|            | getAttributeAccessors() | 1st parameter is now an object that to contains `dataContainer: : DataContainerInterface`. |
+|            | getHoverData() |  New 2nd parameter, an instance of `DataContainerInterface`. |
+|            | getPositionAccessor() | 1st parameter has to be an instance of `DataContainerInterface`. |
+|            | setInitialLayerConfig() | 1st parameter is now object expected to contain `dataContainer: : DataContainerInterface`.  |
+|            | findDefaultLayerProps() | 2nd parameter has to be an instance of `DataContainerInterface`.  |
+| cell-size.js | renderedSize() | `text.rows` is substituted with `text.dataContainer: DataContainerInterface`. |
+| data-table/index.js |  | `DataTable.props.rows` is substituted with `DataTable.props.dataContainer: DataContainerInterface`. |
+| layer-text-label.js | formatTextLabelData() | `dataContainer: DataContainerInterface` is expected as part of the 1st parameter. |
+| geojson-utils.js | getGeojsonDataMaps() | 1st parameter has to be an instance of `DataContainerInterface`. |
+| h3-utils.js | isHexField() | 3rd parameter has to be an instance of `DataContainerInterface`. |
+|             | getHexFields() | 2nd parameter has to be an instance of `DataContainerInterface`. |
+| mapbox-utils.js | geoJsonFromData() | `allData` is removed from the parameter list. `getGeometry`, `getProperties` parameters expect `{index}` object as input parameter. |
+| trip-utils.js | isTripGeoJsonField() | 1st parameter has to be an instance of `DataContainerInterface`. |
+| data-processor.js | formatCsv() | `data` parameter has to be an instance of `DataContainerInterface`. |
+| data-scale-utils.js | getOrdinalDomain() | 1st parameter has to be an instance of `DataContainerInterface`. |
+| filter-utils.js | getFilterFunction() | New 5th parameter, an instance of `DataContainerInterface`. Returned function expects `{index}` object as 1st parameter.  |
+|                 | filterDataByFilterTypes() | 2nd parameter has to be an instance of `DataContainerInterface`. |	
+|                 | getTimestampFieldDomain() | 1st parameter has to be an instance of `DataContainerInterface`. valueAccessor parameter expects a function that accepts `{index}` object as 1st parameter. |		
+|                 | getNumericFieldDomain() |	1st parameter has to be an instance of `DataContainerInterface`. valueAccessor parameter expects a function that accepts `{index}` object as 1st parameter. |
+|                 | getPolygonFilterFunctor() | New 3rd parameter, an instance of `DataContainerInterface`. |
+| interaction-utils.js | getTooltipDisplayDeltaValue() | data and primaryData parameters are now of `DataRow` type. |
+|                      | getTooltipDisplayValue() | data parameter is now of `DataRow` type. |
+| comparison-utils.js |	cmpGpuFilterProp() | New 4th parameter, an instance of `DataContainerInterface`. |
+| gpu-filter-utils.js | getGpuFilterProps() | Returned function now expects a data container. ```dc => (getIndex, getData) => d => {...}``` as parameter to the first call. |
+| data-utils.js | maybeToDate() | New 4th parameter, an instance of `DataContainerInterface`. |
+| kepler-table.js | Field.valueAccessor() | 1st parameter is expected to be an object that contain index property. | 

package/src/utils/table-utils/data-container-interface.d.ts

@@ -0,0 +1,140 @@
+import {DataRow, SharedRowOptions} from './data-row';
+
+/**
+ * Specifies a range of rows of a data container that should be processed.
+ */
+export type RangeOptions = {
+  start?: number;
+  end?: number;
+};
+export interface DataContainerInterface {
+  /**
+   * Returns the number of rows in the data container.
+   * @returns Number of rows in the data container.
+   */
+  numRows(): number;
+
+  /**
+   * Returns the number of columns in the data container.
+   * @returns Number of columns in the data container.
+   */
+  numColumns(): number;
+
+  /**
+   * Returns the value stored at the specified cell in the data container.
+   * @param rowIndex Row index.
+   * @param columnIndex Column index.
+   * @returns Value at the specified cell.
+   */
+  valueAt(rowIndex: number, columnIndex: number): any;
+
+  /**
+   * Returns the row at the specified index.
+   * @param rowIndex Row index.
+   * @param sharedRow Passed row is filled with contents from the specified index and returned without extra row allocations.
+   * @returns A row object.
+   */
+  row(rowIndex: number, sharedRow?: SharedRowOptions): DataRow;
+
+  /**
+   * Returns the specified row of the data container represented as an array.
+   * @param rowIndex Row index.
+   * @returns The specified row represented as an array.
+   */
+  rowAsArray(rowIndex: number): any[];
+
+  /**
+   * Returns an iterator to sequentially access all rows in the data container.
+   * @param sharedRow Indicates that a temporary row object should be used.
+   * If enabled, the returned row object is shared between calls
+   * and mustn't be stored without cloning.
+   * Passed row is filled with contents of the specified row and returned on each iteration.
+   * @returns An iterator to sequentially access all rows in the data container.
+   */
+  rows(sharedRow?: SharedRowOptions): Generator<DataRow, void, any>;
+
+  /**
+   * Returns an iterator to sequentially access all values in the specified column of the data container.
+   * @param columnIndex Column index.
+   * @returns An iterator to all values in the specified column of the data container.
+   */
+  column(columnIndex: number): Generator<any, void, any>;
+
+  /**
+   * Returns contents of the data container as a two-dimensional array.
+   * @returns Data.
+   */
+  flattenData(): any[][];
+
+  /**
+   * Generates an array of indices where each index represents a row in the data container.
+   * @returns An array of indices.
+   */
+  getPlainIndex(): number[];
+
+  /**
+   * Creates a new array populated with the results of calling the provided callback
+   * on every row in the data container.
+   * @param func Callback that is called for every row of the data container.
+   * The callback is called with the following arguments:
+   * - row: The current row being processed in the data container.
+   * - index: The index of the current row being processed in the data container.
+   * @param sharedRow Truthy value indicates that a shared row object should be used.
+   * Make sure the func callback doesn't store the row object in such case,
+   * and clone the row in case you need to store it.
+   * @param options Specify start and end row indices that should be mapped.
+   * @returns A new array with each element being the result of the func callback.
+   */
+  map(
+    func: (row: DataRow, index: number) => any,
+    sharedRow?: SharedRowOptions,
+    options?: RangeOptions
+  ): any[];
+
+  /**
+   * Creates a new array populated with the results of calling the provided callback.
+   * The callback is called for every row in the dataset, but only {index} object is passed.
+   * @param func Callback that is called for every row of the data container.
+   * @param options Specify start and end row indices that should be mapped.
+   * @returns A new array with each element being the result of the func callback.
+   */
+  mapIndex(
+    func: ({index: number}, dataContainer: DataContainerInterface) => any,
+    options?: RangeOptions
+  ): any[];
+
+  /**
+   * Returns the value of the first row in the provided data container that satisfies the provided testing function.
+   * @param func Function to execute on each value in the array.
+   * The function is called with the following arguments:
+   * - row: The current row being processed in the data container.
+   * - index: The index of the current row being processed in the data container.
+   * @param sharedRow Truthy value indicates that a shared row object should be used.
+   * Make sure the func callback doesn't store the row object in such case,
+   * and clone the row in case you need to store it.
+   * @returns First matching row or undefined if no rows satisfy the testing function.
+   */
+  find(
+    func: (row: DataRow, index: number) => any,
+    sharedRow?: SharedRowOptions
+  ): DataRow | undefined;
+
+  /**
+   * Executes a reducer function on each element of the data container, resulting in single output value.
+   * @param func A function to execute on each row in the data container.
+   * The function is called with the following arguments:
+   * - acc: The accumulator accumulates func's return values.
+   * - row: The current row being processed in the data container.
+   * - index: The index of the current row being processed in the data container.
+   * @param initialValue A value to use as the first argument to the first call of the func.
+   * @param sharedRow Truthy value indicates that a shared row object should be used.
+   * Make sure the func callback doesn't store the row object in such case,
+   * and clone the row in case you need to store it.
+   * @returns The single value that results from the reduction.
+   */
+  reduce(
+    func: (acc: any, row: DataRow, index: number) => any,
+    initialValue: any,
+    sharedRow?: SharedRowOptions
+  ): any;
+}

package/src/utils/table-utils/data-container-utils.d.ts

@@ -0,0 +1,43 @@
+import {Field} from './kepler-table';
+import {DataContainerInterface} from './data-container-interface';
+
+type DataForm = {
+  ROWS_ARRAY: string;
+};
+
+export type DataContainerOptions = {
+  inputDataFormat?: string; // one of DataForm
+  fields?: Field[];
+};
+
+/**
+ * Creates a data container wrapper for the data.
+ * @param data Data.
+ * @param options Options.
+ * @returns A data container object which is based on data and options.
+ */
+export function createDataContainer(
+  data: any[],
+  options?: DataContainerOptions
+): DataContainerInterface;
+
+/**
+ * Creates a data container wrapper around another data container.
+ * @param dataContainer Parent data container.
+ * @param indices An array of row indices in the parent data container.
+ */
+export function createIndexedDataContainer(
+  dataContainer: DataContainerInterface,
+  indices: number[]
+): DataContainerInterface;
+
+/**
+ * Get a sample of rows from a data container.
+ * @param dataContainer Data container to get samples from.
+ * @param sampleSize Max number of samples.
+ * @returns A data container which contains samples from the original data container.
+ */
+export function getSampleData(
+  dataContainer: DataContainerInterface,
+  sampleSize?: number
+): DataContainerInterface;

package/src/utils/table-utils/data-container-utils.js

@@ -0,0 +1,61 @@
+// Copyright (c) 2022 Uber Technologies, Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+import {RowDataContainer} from './row-data-container';
+import {IndexedDataContainer} from './indexed-data-container';
+
+/** @type {import('./data-container-utils').DataForm} */
+export const DataForm = {
+  ROWS_ARRAY: 'ROWS_ARRAY'
+};
+
+/** @type {import('./data-container-utils').DataContainerOptions} */
+const defaultOptions = {
+  inputDataFormat: DataForm.ROWS_ARRAY
+};
+
+/** @type {typeof import('./data-container-utils').createDataContainer} */
+export function createDataContainer(data, options = defaultOptions) {
+  options = {...defaultOptions, ...options};
+
+  if (options.inputDataFormat === DataForm.ROWS_ARRAY) {
+    return new RowDataContainer({rows: data, fields: options.fields});
+  }
+
+  throw Error('Failed to create a data container: not implemented format');
+}
+
+/** @type {typeof import('./data-container-utils').createIndexedDataContainer} */
+export function createIndexedDataContainer(dataContainer, indices) {
+  return new IndexedDataContainer(dataContainer, indices);
+}
+
+/** @type {typeof import('./data-container-utils').getSampleData} */
+export function getSampleData(dataContainer, sampleSize = 500) {
+  const numberOfRows = dataContainer.numRows();
+  const sampleStep = Math.max(Math.floor(numberOfRows / sampleSize), 1);
+
+  const indices = [];
+  for (let i = 0; i < numberOfRows; i += sampleStep) {
+    indices.push(i);
+  }
+
+  return createIndexedDataContainer(dataContainer, indices);
+}

package/src/utils/table-utils/data-row.d.ts

@@ -0,0 +1,65 @@
+import {DataContainerInterface} from './data-container-interface';
+
+/**
+ * Setting for shared row optimization.
+ * - False/undefined indicates that unique row objects should be used (default).
+ * - True indicates that a single temporary row object should be created and used without extra allocations.
+ * - A DataRow object indicates that the row should be used as a temporary shared row.
+ * When used, the content of the shared row isn't preserved between calls.
+ */
+export type SharedRowOptions = DataRow | boolean | undefined;
+
+/**
+ * Return type for createSharedRow:
+ * - DataRow object that should be used as shared row.
+ * - Falsy values indicate that shared row object shouldn't be used.
+ */
+export type SharedRowOptionsResult = DataRow | false | undefined;
+
+export class DataRow {
+  /**
+   * Creates new DataRow.
+   * @param dataContainer Data container where data is stored. Can be initialized with null for shared rows.
+   * @param rowIndex Index of a row in the data container.
+   */
+  constructor(dataContainer: DataContainerInterface | null, rowIndex: number);
+
+  /**
+ * Conditionally creates a DataRow object.
+ * @param sharedRowDesc Accepts forllowing options:
+ * - true indicates that new DataRow should be created.
+ * - falsy value or a DataRow object is passed through without any change.
+ * @returns A new DataRow object or unchanged input argument.
+ */
+  static createSharedRow(sharedRowDesc: SharedRowOptions): SharedRowOptionsResult;
+
+  /**
+   * Returns the value stored at the specified index in the row.
+   * @param index Index of the requested field in the row.
+   * @returns Value at the index.
+   */
+  valueAt(index: number): any;
+
+  /**
+   * Returns the row represented as an array.
+   * @returns The row represented as an array.
+   */
+  values(): any[];
+
+  /**
+   * Setup a row object. The method is used by shared rows to prevent excessive allocations.
+   * @param dataContainer Data container.
+   * @param rowIndex Index of a row in the data container.
+   */
+  setSource(dataContainer: DataContainerInterface, rowIndex: number): void;
+
+  /**
+   * Creates a new array populated with the results of calling the provided function
+   * on every element of the row.
+   * @param func The callback is called with the following arguments:
+   * - elem: The current element being processed in the row.
+   * - index: The index of the current element being processed in the row.
+   * @returns A new array with each element being the result of the func callback.
+   */
+  map(func: (elem: any, index: number) => any): any[];
+}