feat(types): Add bounds types (#12)

docs/developer-guide/performance.md

@@ -4,7 +4,7 @@ The code vector and matrix operations in math.gl are based on gl-matrix which is
 
 Since math.gl uses gl-matrix functions under the hood, math.gl's performance is usually very close to gl-matrix, but the additional conveniences in math.gl do come with a certain overhead. Understanding this overhead can help you write more performant code and work around performance issues.
 
-In cases where javascript math calculations are performance critical, you can always use gl-matrix operations directly. See (./docs/get-started/using-with-gl-matrix.md). Essentially, since all math.gl classes inherit from `Array`s they work directly as arguments to gl-matrix functions, no copying necessary.
+In cases where JavaScript math calculations are performance critical, you can always use gl-matrix operations directly. See (./docs/get-started/using-with-gl-matrix.md). Essentially, since all math.gl classes inherit from `Array`s they work directly as arguments to gl-matrix functions, no copying necessary.
 
 ## Disabling Debug Checks
 

docs/docs-sidebar.json

@@ -61,7 +61,8 @@
         "label": "@math.gl/types",
         "items": [
           "modules/types/README",
-          "modules/types/api-reference/array-types"
+          "modules/types/api-reference/array-types",
+          "modules/types/api-reference/bounds"
         ]
       },
       {

docs/modules/types/api-reference/array-types.md

@@ -1,14 +1,18 @@
 # Array Types
 
+math.gl provides a number of numeric array types.
+
+Working with a mix of typed arrays and standard JavaScript arrays containing numbers.
+
 ## Types
 
 ### `TypedArray`
 
-Any javascript typed array
+Any JavaScript typed array
 
 ### `NumericArray`
 
-Any javascript typed array, or any javascript array containing numbers
+Any JavaScript typed array, or any JavaScript array containing numbers
 
 ## Utilities
 

docs/modules/types/api-reference/bounds.md

@@ -0,0 +1,54 @@
+# Bounds
+
+A common need for geospatial and 3D applications is to be able to express bounds
+or extents for a 2D or 3D geometry.
+
+math.gl provides a set of `Bounds*` types. These types could be viewed as a recommendation
+for how vis.gl frameworks should represent bounds.
+Typing out the definitions directly is sometimes easier and clearer than importing these types from math.gl.
+
+## Types
+
+### `Bounds`
+
+2 or 3 dimensional bounds, expressed as an array of arrays `[[minX, minY], [maxX, maxY]]` or `[[minX, minY, minZ], [maxX, maxY, maxZ]]`.
+
+```ts
+export type Bounds =
+  | [[number, number], [number, number]]
+  | [[number, number, number], [number, number, number]];
+```
+
+### `Bounds2D`
+
+2 dimensional bounds, expressed as an array of arrays `[[minX, minY], [maxX, maxY]]`.
+
+```ts
+type Bounds2D = [[number, number], [number, number]];
+```
+
+### `Bounds3D`
+
+3 dimensional bounds, expressed as an array of arrays `[[minX, minY, minZ], [maxX, maxY, maxZ]]`
+
+```ts
+export type Bounds3D = [[number, number, number], [number, number, number]];
+```
+
+## Functions
+
+### `is2DBounds()`
+
+```ts
+is2DBounds(bounds: Bounds): bounds is Bounds2D
+```
+
+Checks if the supplied bounds are 2D and narrows the type to `Bounds2D`.
+
+### `get2DBounds()`
+
+```ts
+get2DBounds(bounds: Bounds): Bounds2D`
+```
+
+Returns 2D bounds, truncating 3D bounds to 2D if needed.

docs/whats-new.md

@@ -45,6 +45,11 @@
   </tbody>
 </table>
 
+
+**`@math.gl/types`**
+
+- New types for expressing [bounds](./modules/types/api-reference/bounds) (extents): `Bounds`, `Bounds2D` and `Bounds3D`.
+- 
 ## v4.0
 
 Release Date: Oct 14, 2023.

modules/types/src/bounds-types.ts

@@ -0,0 +1,29 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** 2 dimensional bounds [[minX, minY], [maxX, maxY]] */
+export type Bounds2D = [[number, number], [number, number]];
+
+/** 3 dimensional bounds [[minX, minY, minZ], [maxX, maxY, maxZ]] */
+export type Bounds3D = [[number, number, number], [number, number, number]];
+
+/** 2 or 3 dimensional bounds [[minX, minY], [maxX, maxY]] or [[minX, minY, minZ], [maxX, maxY, maxZ]] */
+export type Bounds =
+  | [[number, number], [number, number]]
+  | [[number, number, number], [number, number, number]];
+
+/** Checks if a `Bounds` is a `Bounds2D` */
+export function isBounds2D(bounds: Bounds): bounds is Bounds2D {
+  return bounds.length === 2;
+}
+
+/** Accepts 2D and 3D bounds and returns a 2D bound, truncating 3D dimension if necessary */
+export function getBounds2D(bounds: Bounds): Bounds2D {
+  return isBounds2D(bounds)
+    ? bounds
+    : [
+        [bounds[0][0], bounds[0][1]],
+        [bounds[1][0], bounds[1][1]]
+      ];
+}

modules/types/src/index.ts

@@ -4,3 +4,5 @@
 
 export type {TypedArray, TypedArrayConstructor, NumericArray, NumberArray} from './array-types';
 export {isTypedArray, isNumericArray} from './is-array';
+
+export type {Bounds, Bounds2D, Bounds3D} from './bounds-types';

modules/web-mercator/src/fit-bounds.ts

@@ -4,37 +4,38 @@ import {MAX_LATITUDE, lngLatToWorld, worldToLngLat} from './web-mercator-utils';
 
 /**
  * Options for fitBounds
- * @param width - viewport width
- * @param height - viewport height
- * @param bounds - [[lon, lat], [lon, lat]]
- * @param minExtent - The width/height of the bounded area will never be smaller than this
- * @param padding - The amount of padding in pixels
- *  to add to the given bounds. Can also be an object with top, bottom, left and right
- *  properties defining the padding.
- * @param options.offset= - The center of the given bounds relative to the map's center,
  */
 export type FitBoundsOptions = {
+  /**  viewport width  */
   width: number;
+  /**  viewport height  */
   height: number;
+  /**  [[lon, lat], [lon, lat]]  */
   bounds: [[number, number], [number, number]];
-  minExtent?: number; // 0.01 would be about 1000 meters (degree is ~110KM)
+  /**  The width/height of the bounded area will never be smaller than this. 0.01 would be about 1000 meters (degree is ~110KM)  */
+  minExtent?: number;
+  /**  The maximum zoom level to fit the bounds within. */
   maxZoom?: number; // ~x4,000,000 => About 10 meter extents
-  // options
+  /**
+   * padding - The amount of padding in pixels to add to the given bounds.
+   * Can also be an object with top, bottom, left and right properties defining the padding.
+   */
   padding?: number | Padding;
+  /** The center of the given bounds relative to the map's center,  */
   offset?: number[];
 };
 
 /**
  * An object describing the padding to add to the bounds.
- * @property top - Padding from top in pixels to add to the given bounds
- * @property bottom - Padding from bottom in pixels to add to the given bounds
- * @property left - Padding from left in pixels to add to the given bounds
- * @property right - Padding from right in pixels to add to the given bounds
  */
 export type Padding = {
+  /** Padding from top in pixels to add to the given bounds */
   top: number;
+  /** Padding from bottom in pixels to add to the given bounds */
   bottom: number;
+  /** Padding from left in pixels to add to the given bounds */
   left: number;
+  /** Padding from right in pixels to add to the given bounds */
   right: number;
 };