maplibre-gl 3.2.1 → 3.3.0

package/src/symbol/placement.ts

@@ -3,7 +3,7 @@ import type {FeatureKey} from './collision_index';
 import {EXTENT} from '../data/extent';
 import * as symbolSize from './symbol_size';
 import * as projection from './projection';
-import {getAnchorJustification, evaluateVariableOffset} from './symbol_layout';
+import {getAnchorJustification} from './symbol_layout';
 import {getAnchorAlignment, WritingMode} from './shaping';
 import {mat4} from 'gl-matrix';
 import {pixelsToTileUnits} from '../source/pixels_to_tile_units';
@@ -17,12 +17,12 @@ import {getOverlapMode, OverlapMode} from '../style/style_layer/overlap_mode';
 import type {Tile} from '../source/tile';
 import {SymbolBucket, CollisionArrays, SingleCollisionBox} from '../data/bucket/symbol_bucket';
 
-import type {CollisionBoxArray, CollisionVertexArray, SymbolInstance} from '../data/array_types.g';
+import type {CollisionBoxArray, CollisionVertexArray, SymbolInstance, TextAnchorOffset} from '../data/array_types.g';
 import type {FeatureIndex} from '../data/feature_index';
 import type {OverscaledTileID} from '../source/tile_id';
-import type {TextAnchor} from './symbol_layout';
 import {Terrain} from '../render/terrain';
 import {warnOnce} from '../util/util';
+import {TextAnchor, TextAnchorEnum} from '../style/style_layer/variable_text_anchor';
 
 class OpacityState {
     opacity: number;
@@ -147,10 +147,9 @@ function calculateVariableLayoutShift(
     const {horizontalAlign, verticalAlign} = getAnchorAlignment(anchor);
     const shiftX = -(horizontalAlign - 0.5) * width;
     const shiftY = -(verticalAlign - 0.5) * height;
-    const offset = evaluateVariableOffset(anchor, textOffset);
     return new Point(
-        shiftX + offset[0] * textBoxScale,
-        shiftY + offset[1] * textBoxScale
+        shiftX + textOffset[0] * textBoxScale,
+        shiftY + textOffset[1] * textBoxScale
     );
 }
 
@@ -339,7 +338,7 @@ export class Placement {
     }
 
     attemptAnchorPlacement(
-        anchor: TextAnchor,
+        textAnchorOffset: TextAnchorOffset,
         textBox: SingleCollisionBox,
         width: number,
         height: number,
@@ -363,7 +362,8 @@ export class Placement {
             };
         } {
 
-        const textOffset = [symbolInstance.textOffset0, symbolInstance.textOffset1] as [number, number];
+        const anchor = TextAnchorEnum[textAnchorOffset.textAnchor] as TextAnchor;
+        const textOffset = [textAnchorOffset.textOffset0, textAnchorOffset.textOffset1] as [number, number];
         const shift = calculateVariableLayoutShift(anchor, width, height, textOffset, textBoxScale);
 
         const placedGlyphBoxes = this.collisionIndex.placeCollisionBox(
@@ -528,7 +528,11 @@ export class Placement {
                     }
                 };
 
-                if (!layout.get('text-variable-anchor')) {
+                const textAnchorOffsetStart = symbolInstance.textAnchorOffsetStartIndex;
+                const textAnchorOffsetEnd = symbolInstance.textAnchorOffsetEndIndex;
+
+                // If start+end indices match, text-variable-anchor is not in play.
+                if (textAnchorOffsetEnd === textAnchorOffsetStart) {
                     const placeBox = (collisionTextBox, orientation) => {
                         const placedFeature = this.collisionIndex.placeCollisionBox(
                             collisionTextBox,
@@ -561,47 +565,54 @@ export class Placement {
                     updatePreviousOrientationIfNotPlaced(placed && placed.box && placed.box.length);
 
                 } else {
-                    let anchors = layout.get('text-variable-anchor');
-
-                    // If this symbol was in the last placement, shift the previously used
-                    // anchor to the front of the anchor list, only if the previous anchor
-                    // is still in the anchor list
-                    if (this.prevPlacement && this.prevPlacement.variableOffsets[symbolInstance.crossTileID]) {
-                        const prevOffsets = this.prevPlacement.variableOffsets[symbolInstance.crossTileID];
-                        if (anchors.indexOf(prevOffsets.anchor) > 0) {
-                            anchors = anchors.filter(anchor => anchor !== prevOffsets.anchor);
-                            anchors.unshift(prevOffsets.anchor);
-                        }
-                    }
+                    // If this symbol was in the last placement, prefer placement using same anchor, if it's still available
+                    let prevAnchor = TextAnchorEnum[this.prevPlacement?.variableOffsets[symbolInstance.crossTileID]?.anchor];
 
                     const placeBoxForVariableAnchors = (collisionTextBox, collisionIconBox, orientation) => {
                         const width = collisionTextBox.x2 - collisionTextBox.x1;
                         const height = collisionTextBox.y2 - collisionTextBox.y1;
                         const textBoxScale = symbolInstance.textBoxScale;
-
                         const variableIconBox = hasIconTextFit && (iconOverlapMode === 'never') ? collisionIconBox : null;
 
                         let placedBox: {
                             box: Array<number>;
                             offscreen: boolean;
                         } = {box: [], offscreen: false};
-                        const placementAttempts = (textOverlapMode !== 'never') ? anchors.length * 2 : anchors.length;
-                        for (let i = 0; i < placementAttempts; ++i) {
-                            const anchor = anchors[i % anchors.length];
-                            const overlapMode = (i >= anchors.length) ? textOverlapMode : 'never';
-                            const result = this.attemptAnchorPlacement(
-                                anchor, collisionTextBox, width, height,
-                                textBoxScale, rotateWithMap, pitchWithMap, textPixelRatio, posMatrix,
-                                collisionGroup, overlapMode, symbolInstance, bucket, orientation, variableIconBox, getElevation);
-
-                            if (result) {
-                                placedBox = result.placedGlyphBoxes;
-                                if (placedBox && placedBox.box && placedBox.box.length) {
-                                    placeText = true;
-                                    shift = result.shift;
-                                    break;
+                        let placementPasses = (textOverlapMode === 'never') ? 1 : 2;
+                        let overlapMode: OverlapMode = 'never';
+
+                        if (prevAnchor) {
+                            placementPasses++;
+                        }
+
+                        for (let pass = 0; pass < placementPasses; pass++) {
+                            for (let i = textAnchorOffsetStart; i < textAnchorOffsetEnd; i++) {
+                                const textAnchorOffset = bucket.textAnchorOffsets.get(i);
+
+                                if (prevAnchor && textAnchorOffset.textAnchor !== prevAnchor) {
+                                    continue;
+                                }
+
+                                const result = this.attemptAnchorPlacement(
+                                    textAnchorOffset, collisionTextBox, width, height,
+                                    textBoxScale, rotateWithMap, pitchWithMap, textPixelRatio, posMatrix,
+                                    collisionGroup, overlapMode, symbolInstance, bucket, orientation, variableIconBox, getElevation);
+
+                                if (result) {
+                                    placedBox = result.placedGlyphBoxes;
+                                    if (placedBox && placedBox.box && placedBox.box.length) {
+                                        placeText = true;
+                                        shift = result.shift;
+                                        return placedBox;
+                                    }
                                 }
                             }
+
+                            if (prevAnchor) {
+                                prevAnchor = null;
+                            } else {
+                                overlapMode = textOverlapMode;
+                            }
                         }
 
                         return placedBox;
@@ -952,11 +963,12 @@ export class Placement {
         if (bucket.hasIconCollisionBoxData()) bucket.iconCollisionBox.collisionVertexArray.clear();
         if (bucket.hasTextCollisionBoxData()) bucket.textCollisionBox.collisionVertexArray.clear();
 
-        const layout = bucket.layers[0].layout;
+        const layer = bucket.layers[0];
+        const layout = layer.layout;
         const duplicateOpacityState = new JointOpacityState(null, 0, false, false, true);
         const textAllowOverlap = layout.get('text-allow-overlap');
         const iconAllowOverlap = layout.get('icon-allow-overlap');
-        const variablePlacement = layout.get('text-variable-anchor');
+        const hasVariablePlacement = layer._unevaluatedLayout.hasValue('text-variable-anchor') || layer._unevaluatedLayout.hasValue('text-variable-anchor-offset');
         const rotateWithMap = layout.get('text-rotation-alignment') === 'map';
         const pitchWithMap = layout.get('text-pitch-alignment') === 'map';
         const hasIconTextFit = layout.get('icon-text-fit') !== 'none';
@@ -1074,7 +1086,7 @@ export class Placement {
                     let shift = new Point(0, 0);
                     if (collisionArrays.textBox || collisionArrays.verticalTextBox) {
                         let used = true;
-                        if (variablePlacement) {
+                        if (hasVariablePlacement) {
                             const variableOffset = this.variableOffsets[crossTileID];
                             if (variableOffset) {
                                 // This will show either the currently placed position or the last

package/src/symbol/symbol_layout.ts

@@ -19,7 +19,7 @@ import {SIZE_PACK_FACTOR, MAX_PACKED_SIZE, MAX_GLYPH_ICON_SIZE} from './symbol_s
 import ONE_EM from './one_em';
 import type {CanonicalTileID} from '../source/tile_id';
 import type {Shaping, PositionedIcon, TextJustify} from './shaping';
-import type {CollisionBoxArray} from '../data/array_types.g';
+import type {CollisionBoxArray, TextAnchorOffsetArray} from '../data/array_types.g';
 import type {SymbolFeature} from '../data/bucket/symbol_bucket';
 import type {StyleImage} from '../style/style_image';
 import type {StyleGlyph} from '../style/style_glyph';
@@ -31,6 +31,8 @@ import type {PossiblyEvaluatedPropertyValue} from '../style/properties';
 import Point from '@mapbox/point-geometry';
 import murmur3 from 'murmurhash-js';
 import {getIconPadding, SymbolPadding} from '../style/style_layer/symbol_style_layer';
+import {VariableAnchorOffsetCollection} from '@maplibre/maplibre-gl-style-spec';
+import {getTextVariableAnchorOffset, evaluateVariableOffset, INVALID_TEXT_OFFSET, TextAnchor, TextAnchorEnum} from '../style/style_layer/variable_text_anchor';
 
 // The symbol layout process needs `text-size` evaluated at up to five different zoom levels, and
 // `icon-size` at up to three:
@@ -59,98 +61,6 @@ type ShapedTextOrientations = {
     horizontal: Record<TextJustify, Shaping>;
 };
 
-export type TextAnchor = 'center' | 'left' | 'right' | 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-
-// The radial offset is to the edge of the text box
-// In the horizontal direction, the edge of the text box is where glyphs start
-// But in the vertical direction, the glyphs appear to "start" at the baseline
-// We don't actually load baseline data, but we assume an offset of ONE_EM - 17
-// (see "yOffset" in shaping.js)
-const baselineOffset = 7;
-const INVALID_TEXT_OFFSET = Number.POSITIVE_INFINITY;
-
-export function evaluateVariableOffset(anchor: TextAnchor, offset: [number, number]) {
-
-    function fromRadialOffset(anchor: TextAnchor, radialOffset: number) {
-        let x = 0, y = 0;
-        if (radialOffset < 0) radialOffset = 0; // Ignore negative offset.
-        // solve for r where r^2 + r^2 = radialOffset^2
-        const hypotenuse = radialOffset / Math.sqrt(2);
-        switch (anchor) {
-            case 'top-right':
-            case 'top-left':
-                y = hypotenuse - baselineOffset;
-                break;
-            case 'bottom-right':
-            case 'bottom-left':
-                y = -hypotenuse + baselineOffset;
-                break;
-            case 'bottom':
-                y = -radialOffset + baselineOffset;
-                break;
-            case 'top':
-                y = radialOffset - baselineOffset;
-                break;
-        }
-
-        switch (anchor) {
-            case 'top-right':
-            case 'bottom-right':
-                x = -hypotenuse;
-                break;
-            case 'top-left':
-            case 'bottom-left':
-                x = hypotenuse;
-                break;
-            case 'left':
-                x = radialOffset;
-                break;
-            case 'right':
-                x = -radialOffset;
-                break;
-        }
-
-        return [x, y];
-    }
-
-    function fromTextOffset(anchor: TextAnchor, offsetX: number, offsetY: number) {
-        let x = 0, y = 0;
-        // Use absolute offset values.
-        offsetX = Math.abs(offsetX);
-        offsetY = Math.abs(offsetY);
-
-        switch (anchor) {
-            case 'top-right':
-            case 'top-left':
-            case 'top':
-                y = offsetY - baselineOffset;
-                break;
-            case 'bottom-right':
-            case 'bottom-left':
-            case 'bottom':
-                y = -offsetY + baselineOffset;
-                break;
-        }
-
-        switch (anchor) {
-            case 'top-right':
-            case 'bottom-right':
-            case 'right':
-                x = -offsetX;
-                break;
-            case 'top-left':
-            case 'bottom-left':
-            case 'left':
-                x = offsetX;
-                break;
-        }
-
-        return [x, y];
-    }
-
-    return (offset[1] !== INVALID_TEXT_OFFSET) ? fromTextOffset(anchor, offset[0], offset[1]) : fromRadialOffset(anchor, offset[0]);
-}
-
 export function performSymbolLayout(args: {
     bucket: SymbolBucket;
     glyphMap: {
@@ -175,8 +85,9 @@ export function performSymbolLayout(args: {
     args.bucket.compareText = {};
     args.bucket.iconsNeedLinear = false;
 
-    const layout = args.bucket.layers[0].layout;
-    const unevaluatedLayoutValues = args.bucket.layers[0]._unevaluatedLayout._values;
+    const layer = args.bucket.layers[0];
+    const layout = layer.layout;
+    const unevaluatedLayoutValues = layer._unevaluatedLayout._values;
 
     const sizes: Sizes = {
         // Filled in below, if *SizeData.kind is 'composite'
@@ -226,16 +137,16 @@ export function performSymbolLayout(args: {
             const spacingIfAllowed = allowsLetterSpacing(unformattedText) ? spacing : 0;
 
             const textAnchor = layout.get('text-anchor').evaluate(feature, {}, args.canonical);
-            const variableTextAnchor = layout.get('text-variable-anchor');
+            const variableAnchorOffset = getTextVariableAnchorOffset(layer, feature, args.canonical);
 
-            if (!variableTextAnchor) {
+            if (!variableAnchorOffset) {
                 const radialOffset = layout.get('text-radial-offset').evaluate(feature, {}, args.canonical);
                 // Layers with variable anchors use the `text-radial-offset` property and the [x, y] offset vector
                 // is calculated at placement time instead of layout time
                 if (radialOffset) {
                     // The style spec says don't use `text-offset` and `text-radial-offset` together
                     // but doesn't actually specify what happens if you use both. We go with the radial offset.
-                    textOffset = evaluateVariableOffset(textAnchor, [radialOffset * ONE_EM, INVALID_TEXT_OFFSET]) as [number, number];
+                    textOffset = evaluateVariableOffset(textAnchor, [radialOffset * ONE_EM, INVALID_TEXT_OFFSET]);
                 } else {
                     textOffset = (layout.get('text-offset').evaluate(feature, {}, args.canonical).map(t => t * ONE_EM) as [number, number]);
                 }
@@ -261,14 +172,19 @@ export function performSymbolLayout(args: {
             };
 
             // If this layer uses text-variable-anchor, generate shapings for all justification possibilities.
-            if (!textAlongLine && variableTextAnchor) {
-                const justifications = textJustify === 'auto' ?
-                    variableTextAnchor.map(a => getAnchorJustification(a)) :
-                    [textJustify];
+            if (!textAlongLine && variableAnchorOffset) {
+                const justifications = new Set<TextJustify>();
+
+                if (textJustify === 'auto') {
+                    for (let i = 0; i < variableAnchorOffset.values.length; i += 2) {
+                        justifications.add(getAnchorJustification(variableAnchorOffset.values[i] as TextAnchor));
+                    }
+                } else {
+                    justifications.add(textJustify);
+                }
 
                 let singleLine = false;
-                for (let i = 0; i < justifications.length; i++) {
-                    const justification: TextJustify = justifications[i];
+                for (const justification of justifications) {
                     if (shapedTextOrientations.horizontal[justification]) continue;
                     if (singleLine) {
                         // If the shaping for the first justification was only a single line, we
@@ -486,6 +402,22 @@ function addFeature(bucket: SymbolBucket,
     }
 }
 
+function addTextVariableAnchorOffsets(textAnchorOffsets: TextAnchorOffsetArray, variableAnchorOffset: VariableAnchorOffsetCollection): [number, number] {
+    const startIndex = textAnchorOffsets.length;
+    const values = variableAnchorOffset?.values;
+
+    if (values?.length > 0) {
+        for (let i = 0; i < values.length; i += 2) {
+            const anchor = TextAnchorEnum[values[i] as TextAnchor];
+            const offset = values[i + 1] as [number, number];
+
+            textAnchorOffsets.emplaceBack(anchor, offset[0], offset[1]);
+        }
+    }
+
+    return [startIndex, textAnchorOffsets.length];
+}
+
 function addTextVertices(bucket: SymbolBucket,
     anchor: Point,
     shapedText: Shaping,
@@ -602,15 +534,6 @@ function addSymbol(bucket: SymbolBucket,
     const placedTextSymbolIndices: {[k: string]: number} = {};
     let key = murmur3('');
 
-    let textOffset0 = 0;
-    let textOffset1 = 0;
-    if (layer._unevaluatedLayout.getValue('text-radial-offset') === undefined) {
-        [textOffset0, textOffset1] = (layer.layout.get('text-offset').evaluate(feature, {}, canonical).map(t => t * ONE_EM) as [number, number]);
-    } else {
-        textOffset0 = layer.layout.get('text-radial-offset').evaluate(feature, {}, canonical) * ONE_EM;
-        textOffset1 = INVALID_TEXT_OFFSET;
-    }
-
     if (bucket.allowVerticalPlacement && shapedTextOrientations.vertical) {
         const textRotation = layer.layout.get('text-rotate').evaluate(feature, {}, canonical);
         const verticalTextRotation = textRotation + 90.0;
@@ -763,6 +686,9 @@ function addSymbol(bucket: SymbolBucket,
         bucket.addToSortKeyRanges(bucket.symbolInstances.length, feature.sortKey as number);
     }
 
+    const variableAnchorOffset = getTextVariableAnchorOffset(layer, feature, canonical);
+    const [textAnchorOffsetStartIndex, textAnchorOffsetEndIndex] = addTextVariableAnchorOffsets(bucket.textAnchorOffsets, variableAnchorOffset);
+
     bucket.symbolInstances.emplaceBack(
         anchor.x,
         anchor.y,
@@ -789,9 +715,9 @@ function addSymbol(bucket: SymbolBucket,
         useRuntimeCollisionCircles,
         0,
         textBoxScale,
-        textOffset0,
-        textOffset1,
-        collisionCircleDiameter);
+        collisionCircleDiameter,
+        textAnchorOffsetStartIndex,
+        textAnchorOffsetEndIndex);
 }
 
 function anchorIsTooClose(bucket: SymbolBucket, text: string, repeatDistance: number, anchor: Point) {

package/src/ui/camera.ts

@@ -263,30 +263,30 @@ export abstract class Camera extends Evented {
     _easeFrameId: TaskID;
 
     /**
-     * @hidden
+     * @internal
      * holds the geographical coordinate of the target
      */
     _elevationCenter: LngLat;
     /**
-     * @hidden
+     * @internal
      * holds the targ altitude value, = center elevation of the target.
      * This value may changes during flight, because new terrain-tiles loads during flight.
      */
     _elevationTarget: number;
     /**
-     * @hidden
+     * @internal
      * holds the start altitude value, = center elevation before animation begins
      * this value will recalculated during flight in respect of changing _elevationTarget values,
      * so the linear interpolation between start and target keeps smooth and without jumps.
      */
     _elevationStart: number;
     /**
-     * @hidden
+     * @internal
      * Saves the current state of the elevation freeze - this is used during map movement to prevent "rocky" camera movement.
      */
     _elevationFreeze: boolean;
     /**
-     * @hidden
+     * @internal
      * Used to track accumulated changes during continuous interaction
      */
     _requestedCameraState?: Transform;
@@ -645,6 +645,7 @@ export abstract class Camera extends Evented {
     }
 
     /**
+     * @internal
      * Calculate the center of these two points in the viewport and use
      * the highest zoom level up to and including `Map#getMaxZoom()` that fits
      * the points in the viewport at the specified bearing.
@@ -654,7 +655,6 @@ export abstract class Camera extends Evented {
      * @param options - the camera options
      * @returns If map is able to fit to provided bounds, returns `center`, `zoom`, and `bearing`.
      *      If map is unable to fit, method will warn and return undefined.
-     * @hidden
      * @example
      * ```ts
      * let p0 = [-79, 43];
@@ -1085,11 +1085,11 @@ export abstract class Camera extends Evented {
     }
 
     /**
+     * @internal
      * Called when the camera is about to be manipulated.
      * If `transformCameraUpdate` is specified, a copy of the current transform is created to track the accumulated changes.
      * This underlying transform represents the "desired state" proposed by input handlers / animations / UI controls.
      * It may differ from the state used for rendering (`this.transform`).
-     * @hidden
      * @returns Transform to apply changes to
      */
     _getTransformForUpdate(): Transform {
@@ -1102,8 +1102,8 @@ export abstract class Camera extends Evented {
     }
 
     /**
+     * @internal
      * Called after the camera is done being manipulated.
-     * @hidden
      * @param tr - the requested camera end state
      * Call `transformCameraUpdate` if present, and then apply the "approved" changes.
      */

package/src/ui/handler/box_zoom.ts

@@ -25,9 +25,7 @@ export class BoxZoomHandler implements Handler {
     _box: HTMLElement;
     _clickTolerance: number;
 
-    /**
-     * @hidden
-     */
+    /** @internal */
     constructor(map: Map, options: {
         clickTolerance: number;
     }) {

package/src/ui/handler/click_zoom.ts

@@ -13,9 +13,7 @@ export class ClickZoomHandler implements Handler {
     _enabled: boolean;
     _active: boolean;
 
-    /**
-     * @hidden
-    */
+    /** @internal */
     constructor(map: Map) {
         this._tr = new TransformProvider(map);
         this.reset();

package/src/ui/handler/keyboard.ts

@@ -33,9 +33,7 @@ export class KeyboardHandler implements Handler {
     _pitchStep: number;
     _rotationDisabled: boolean;
 
-    /**
-    * @hidden
-    */
+    /** @internal */
     constructor(map: Map) {
         this._tr = new TransformProvider(map);
         const stepOptions = defaultOptions;

package/src/ui/handler/scroll_zoom.ts

@@ -62,9 +62,7 @@ export class ScrollZoomHandler implements Handler {
     _defaultZoomRate: number;
     _wheelZoomRate: number;
 
-    /**
-     * @hidden
-     */
+    /** @internal */
     constructor(map: Map, triggerRenderFrame: () => void) {
         this._map = map;
         this._tr = new TransformProvider(map);

package/src/ui/handler/shim/dblclick_zoom.ts

@@ -12,9 +12,7 @@ export class DoubleClickZoomHandler {
     _clickZoom: ClickZoomHandler;
     _tapZoom: TapZoomHandler;
 
-    /**
-     * @hidden
-    */
+    /** @internal */
     constructor(clickZoom: ClickZoomHandler, TapZoom: TapZoomHandler) {
         this._clickZoom = clickZoom;
         this._tapZoom = TapZoom;

package/src/ui/handler/shim/drag_pan.ts

@@ -41,9 +41,7 @@ export class DragPanHandler {
     _touchPan: TouchPanHandler;
     _inertiaOptions: DragPanOptions | boolean;
 
-    /**
-     * @hidden
-    */
+    /** @internal */
     constructor(el: HTMLElement, mousePan: MousePanHandler, touchPan: TouchPanHandler) {
         this._el = el;
         this._mousePan = mousePan;

package/src/ui/handler/shim/drag_rotate.ts

@@ -20,9 +20,7 @@ export class DragRotateHandler {
     _mousePitch: MousePitchHandler;
     _pitchWithRotate: boolean;
 
-    /**
-     * @hidden
-    */
+    /** @internal */
     constructor(options: DragRotateHandlerOptions, mouseRotate: MouseRotateHandler, mousePitch: MousePitchHandler) {
         this._pitchWithRotate = options.pitchWithRotate;
         this._mouseRotate = mouseRotate;

package/src/ui/handler/shim/two_fingers_touch.ts

@@ -19,9 +19,7 @@ export class TwoFingersTouchZoomRotateHandler {
     _rotationDisabled: boolean;
     _enabled: boolean;
 
-    /**
-     * @hidden
-    */
+    /** @internal */
     constructor(el: HTMLElement, touchZoom: TwoFingersTouchZoomHandler, touchRotate: TwoFingersTouchRotateHandler, tapDragZoom: TapDragZoomHandler) {
         this._el = el;
         this._touchZoom = touchZoom;

package/src/ui/handler/transform-provider.ts

@@ -5,6 +5,7 @@ import Point from '@mapbox/point-geometry';
 import {LngLat} from '../../geo/lng_lat';
 
 /**
+ * @internal
  * Shared utilities for the Handler classes to access the correct camera state.
  * If Camera.transformCameraUpdate is specified, the "desired state" of camera may differ from the state used for rendering.
  * The handlers need the "desired state" to track accumulated changes.

package/src/ui/handler/two_fingers_touch.ts

@@ -27,9 +27,7 @@ abstract class TwoFingersTouchHandler implements Handler {
     _startVector: Point;
     _aroundCenter: boolean;
 
-    /**
-     * @hidden
-     */
+    /** @internal */
     constructor() {
         this.reset();
     }

package/src/ui/map.ts

@@ -504,7 +504,7 @@ export class Map extends Camera {
     _terrainDataCallback: (e: MapStyleDataEvent | MapSourceDataEvent) => void;
 
     /**
-     * @hidden
+     * @internal
      * image queue throttling handle. To be used later when clean up
      */
     _imageQueueHandle: number;
@@ -707,9 +707,9 @@ export class Map extends Camera {
     }
 
     /**
+     * @internal
      * Returns a unique number for this map instance which is used for the MapLoadEvent
      * to make sure we only fire one event per instantiated map object.
-     * @hidden
      * @returns the uniq map ID
      */
     _getMapId() {
@@ -868,9 +868,9 @@ export class Map extends Camera {
     }
 
     /**
+     * @internal
      * Return the map's pixel ratio eventually scaled down to respect maxCanvasSize.
      * Internally you should use this and not getPixelRatio().
-     * @hidden
      */
     _getClampedPixelRatio(width: number, height: number): number {
         const {0: maxCanvasWidth, 1: maxCanvasHeight} = this._maxCanvasSize;
@@ -3070,9 +3070,9 @@ export class Map extends Camera {
     }
 
     /**
+     * @internal
      * Update this map's style and sources, and re-render the map.
      *
-     * @hidden
      * @param updateStyle - mark the map's style for reprocessing as
      * well as its sources
      * @returns `this`
@@ -3088,9 +3088,10 @@ export class Map extends Camera {
     }
 
     /**
+     * @internal
      * Request that the given callback be executed during the next render
      * frame.  Schedule a render frame if one is not already scheduled.
-     * @hidden
+     *
      * @returns An id that can be used to cancel the callback
      */
     _requestRenderFrame(callback: () => void): TaskID {
@@ -3103,6 +3104,7 @@ export class Map extends Camera {
     }
 
     /**
+     * @internal
      * Call when a (re-)render of the map is required:
      * - The style has changed (`setPaintProperty()`, etc.)
      * - Source data has changed (e.g. tiles have finished loading)
@@ -3110,7 +3112,6 @@ export class Map extends Camera {
      * - A transition is in progress
      *
      * @param paintStartTimeStamp - The time when the animation frame began executing.
-     * @hidden
      *
      * @returns `this`
      */