🤖 Merge PR DefinitelyTyped#73657 feat(plotly.js): add jsdoc for MapboxLayers, fix a few attributes by @hkleungai

hkleungai · web-flow · commit 2dc090277668 · 2025-09-15T09:01:32.000-07:00
diff --git a/types/plotly.js/index.d.ts b/types/plotly.js/index.d.ts
@@ -156,16 +156,42 @@ export interface LegendClickEvent {
 }
 
 export interface MapboxCenter {
+    /**
+     * Sets the latitude of the center of the map (in degrees North).
+     */
     lon: number;
+    /**
+     * Sets the longitude of the center of the map (in degrees East).
+     */
     lat: number;
 }
 
 export interface MapboxSymbol {
+    /**
+     * Sets the symbol icon image (mapbox.layer.layout.icon-image).
+     * Full list: https://www.mapbox.com/maki-icons/
+     */
     icon: string;
+    /**
+     * Sets the symbol icon size (mapbox.layer.layout.icon-size).
+     * Has an effect only when `type` is set to *symbol*.
+     */
     iconsize: number;
+    /**
+     * Sets the symbol text (mapbox.layer.layout.text-field).
+     */
     text: string;
+    /**
+     * Sets the symbol and/or text placement (mapbox.layer.layout.symbol-placement).
+     * If `placement` is *point*, the label is placed where the geometry is located.
+     * If `placement` is *line*, the label is placed along the line of the geometry.
+     * If `placement` is *line-center*, the label is placed on the center of the geometry.
+     */
     placement: "point" | "line" | "line-center";
     textfont: Partial<Font>;
+    /**
+     * Sets the positions of the `text` elements with respects to the (x,y) coordinates.
+     */
     textposition:
         | "top left"
         | "top center"
@@ -176,23 +202,106 @@ export interface MapboxSymbol {
         | "bottom right";
 }
 export interface MapboxLayers {
-    visible: true;
+    /**
+     * Determines whether this layer is displayed.
+     */
+    visible: boolean;
+    /**
+     * Sets the source type for this layer, that is the type of the layer data.
+     */
     sourcetype: "geojson" | "vecotr" | "raster" | "image";
-    source: number | string;
+    /**
+     * Sets the source data for this layer (mapbox.layer.source).
+     * When `sourcetype` is set to *geojson*, `source` can be a URL to a GeoJSON or a GeoJSON object.
+     * When `sourcetype` is set to *vector* or *raster*, `source` can be a URL or an array of tile URLs.
+     * When `sourcetype` is set to *image*, `source` can be a URL to an image.
+     */
+    source: any;
+    /**
+     * Specifies the layer to use from a vector tile source (mapbox.layer.source-layer).
+     * Required for *vector* source type that supports multiple layers.
+     */
     sourcelayer: string;
+    /**
+     * Sets the attribution for this source.
+     */
     sourceattribution: string;
+    /**
+     * Sets the layer type,
+     * that is the how the layer data set in `source` will be rendered With `sourcetype` set to *geojson*,
+     * the following values are allowed: *circle*, *line*, *fill* and *symbol*.
+     * But note that *line* and *fill* are not compatible with Point GeoJSON geometries.
+     * With `sourcetype` set to *vector*, the following values are allowed: *circle*, *line*, *fill* and *symbol*.
+     * With `sourcetype` set to *raster* or `*image*`, only the *raster* value is allowed.
+     */
     type: "circle" | "line" | "fill" | "symbol" | "raster";
+    /**
+     * Sets the coordinates array contains [longitude, latitude] pairs for the image corners listed in clockwise order: top left, top right, bottom right, bottom left.
+     * Only has an effect for *image* `sourcetype`.
+     */
     coordinates: number | string;
+    /**
+     * Determines if the layer will be inserted before the layer with the specified ID.
+     * If omitted or set to '', the layer will be inserted above every existing layer.
+     */
     below: string;
+    /**
+     * Sets the primary layer color.
+     * If `type` is *circle*, color corresponds to the circle color (mapbox.layer.paint.circle-color).
+     * If `type` is *line*, color corresponds to the line color (mapbox.layer.paint.line-color).
+     * If `type` is *fill*, color corresponds to the fill color (mapbox.layer.paint.fill-color).
+     * If `type` is *symbol*, color corresponds to the icon color (mapbox.layer.paint.icon-color).
+     */
     color: Color;
+    /**
+     * Sets the opacity of the layer.
+     * If `type` is *circle*, opacity corresponds to the circle opacity (mapbox.layer.paint.circle-opacity).
+     * If `type` is *line*, opacity corresponds to the line opacity (mapbox.layer.paint.line-opacity).
+     * If `type` is *fill*, opacity corresponds to the fill opacity (mapbox.layer.paint.fill-opacity).
+     * If `type` is *symbol*, opacity corresponds to the icon/text opacity (mapbox.layer.paint.text-opacity).
+     */
     opacity: number;
+    /**
+     * Sets the minimum zoom level (mapbox.layer.minzoom).
+     * At zoom levels less than the minzoom, the layer will be hidden.
+     */
     minzoom: number;
+    /**
+     * Sets the maximum zoom level (mapbox.layer.maxzoom).
+     * At zoom levels equal to or greater than the maxzoom, the layer will be hidden.
+     */
     maxzoom: number;
-    circle: { radius: number };
+    circle: {
+        /**
+         * Sets the circle radius (mapbox.layer.paint.circle-radius).
+         * Has an effect only when `type` is set to *circle*.
+         */
+        radius: number;
+    };
     line: Partial<ShapeLine>;
-    fill: { outlinecolor: Color };
+    fill: {
+        /**
+         * Sets the fill outline color (mapbox.layer.paint.fill-outline-color).
+         * Has an effect only when `type` is set to *fill*.
+         */
+        outlinecolor: Color;
+    };
     symbol: Partial<MapboxSymbol>;
+    /**
+     * When used in a template, named items are created in the output figure in addition to any items the figure already has in this array.
+     * You can modify these items in the output figure by making your own item with `templateitemname` matching this `name`
+     * alongside your modifications (including `visible: false` or `enabled: false` to hide it).
+     * Has no effect outside of a template.
+     */
     name: string;
+    /**
+     * Used to refer to a named item in this array in the template.
+     * Named items from the template will be created even without a matching item in the input figure,
+     * but you can modify one by making an item with `templateitemname` matching its `name`,
+     * alongside your modifications (including `visible: false` or `enabled: false` to hide it).
+     * If there is no template or no matching item,
+     * this item will be hidden unless you explicitly show it with `visible: true`.
+     */
     templateitemname: string;
 }
 
diff --git a/types/plotly.js/test/index-tests.ts b/types/plotly.js/test/index-tests.ts
@@ -1241,7 +1241,80 @@ function rand() {
             bearing: 30,
             bounds: { east: 0, west: 0, south: 0, north: 0 },
             pitch: 0,
-            layers: [],
+            layers: [
+                {
+                    // Circle layer
+                    visible: true,
+                    sourcetype: "geojson",
+                    source: {
+                        type: "Feature",
+                        properties: {},
+                        geometry: {
+                            type: "Point",
+                            coordinates: [-74.0060, 40.7128],
+                        },
+                    },
+                    type: "circle",
+                    circle: { radius: 10 },
+                    color: "rgb(255, 0, 0)",
+                    opacity: 0.8,
+                    minzoom: 8,
+                    maxzoom: 15,
+                },
+                {
+                    // Line layer
+                    visible: true,
+                    sourcetype: "geojson",
+                    source: {
+                        type: "Feature",
+                        geometry: {
+                            type: "LineString",
+                            coordinates: [
+                                [-74.0060, 40.7128],
+                                [-73.9857, 40.7484],
+                            ],
+                        },
+                    },
+                    type: "line",
+                    line: {
+                        color: "#00ff00",
+                        width: 2,
+                        dash: "dashdot",
+                    },
+                    opacity: 0.6,
+                },
+                {
+                    // Symbol layer
+                    visible: true,
+                    sourcetype: "geojson",
+                    source: {
+                        type: "Feature",
+                        geometry: {
+                            type: "Point",
+                            coordinates: [-73.9857, 40.7484],
+                        },
+                    },
+                    type: "symbol",
+                    symbol: {
+                        icon: "monument",
+                        iconsize: 1.5,
+                        text: "Empire State",
+                        placement: "point",
+                        textposition: "top center",
+                        textfont: font,
+                    },
+                },
+                {
+                    // Raster layer
+                    visible: true,
+                    sourcetype: "raster",
+                    source: "mapbox://mapbox.satellite",
+                    type: "raster",
+                    opacity: 0.7,
+                    minzoom: 0,
+                    maxzoom: 22,
+                },
+            ],
             uirevision: "uirevision",
         },
         margin: { r: 0, t: 0, b: 0, l: 0 },
diff --git a/types/plotly.js/v2/index.d.ts b/types/plotly.js/v2/index.d.ts
@@ -156,16 +156,42 @@ export interface LegendClickEvent {
 }
 
 export interface MapboxCenter {
+    /**
+     * Sets the latitude of the center of the map (in degrees North).
+     */
     lon: number;
+    /**
+     * Sets the longitude of the center of the map (in degrees East).
+     */
     lat: number;
 }
 
 export interface MapboxSymbol {
+    /**
+     * Sets the symbol icon image (mapbox.layer.layout.icon-image).
+     * Full list: https://www.mapbox.com/maki-icons/
+     */
     icon: string;
+    /**
+     * Sets the symbol icon size (mapbox.layer.layout.icon-size).
+     * Has an effect only when `type` is set to *symbol*.
+     */
     iconsize: number;
+    /**
+     * Sets the symbol text (mapbox.layer.layout.text-field).
+     */
     text: string;
+    /**
+     * Sets the symbol and/or text placement (mapbox.layer.layout.symbol-placement).
+     * If `placement` is *point*, the label is placed where the geometry is located.
+     * If `placement` is *line*, the label is placed along the line of the geometry.
+     * If `placement` is *line-center*, the label is placed on the center of the geometry.
+     */
     placement: "point" | "line" | "line-center";
     textfont: Partial<Font>;
+    /**
+     * Sets the positions of the `text` elements with respects to the (x,y) coordinates.
+     */
     textposition:
         | "top left"
         | "top center"
@@ -176,23 +202,106 @@ export interface MapboxSymbol {
         | "bottom right";
 }
 export interface MapboxLayers {
-    visible: true;
+    /**
+     * Determines whether this layer is displayed.
+     */
+    visible: boolean;
+    /**
+     * Sets the source type for this layer, that is the type of the layer data.
+     */
     sourcetype: "geojson" | "vecotr" | "raster" | "image";
-    source: number | string;
+    /**
+     * Sets the source data for this layer (mapbox.layer.source).
+     * When `sourcetype` is set to *geojson*, `source` can be a URL to a GeoJSON or a GeoJSON object.
+     * When `sourcetype` is set to *vector* or *raster*, `source` can be a URL or an array of tile URLs.
+     * When `sourcetype` is set to *image*, `source` can be a URL to an image.
+     */
+    source: any;
+    /**
+     * Specifies the layer to use from a vector tile source (mapbox.layer.source-layer).
+     * Required for *vector* source type that supports multiple layers.
+     */
     sourcelayer: string;
+    /**
+     * Sets the attribution for this source.
+     */
     sourceattribution: string;
+    /**
+     * Sets the layer type,
+     * that is the how the layer data set in `source` will be rendered With `sourcetype` set to *geojson*,
+     * the following values are allowed: *circle*, *line*, *fill* and *symbol*.
+     * But note that *line* and *fill* are not compatible with Point GeoJSON geometries.
+     * With `sourcetype` set to *vector*, the following values are allowed: *circle*, *line*, *fill* and *symbol*.
+     * With `sourcetype` set to *raster* or `*image*`, only the *raster* value is allowed.
+     */
     type: "circle" | "line" | "fill" | "symbol" | "raster";
+    /**
+     * Sets the coordinates array contains [longitude, latitude] pairs for the image corners listed in clockwise order: top left, top right, bottom right, bottom left.
+     * Only has an effect for *image* `sourcetype`.
+     */
     coordinates: number | string;
+    /**
+     * Determines if the layer will be inserted before the layer with the specified ID.
+     * If omitted or set to '', the layer will be inserted above every existing layer.
+     */
     below: string;
+    /**
+     * Sets the primary layer color.
+     * If `type` is *circle*, color corresponds to the circle color (mapbox.layer.paint.circle-color).
+     * If `type` is *line*, color corresponds to the line color (mapbox.layer.paint.line-color).
+     * If `type` is *fill*, color corresponds to the fill color (mapbox.layer.paint.fill-color).
+     * If `type` is *symbol*, color corresponds to the icon color (mapbox.layer.paint.icon-color).
+     */
     color: Color;
+    /**
+     * Sets the opacity of the layer.
+     * If `type` is *circle*, opacity corresponds to the circle opacity (mapbox.layer.paint.circle-opacity).
+     * If `type` is *line*, opacity corresponds to the line opacity (mapbox.layer.paint.line-opacity).
+     * If `type` is *fill*, opacity corresponds to the fill opacity (mapbox.layer.paint.fill-opacity).
+     * If `type` is *symbol*, opacity corresponds to the icon/text opacity (mapbox.layer.paint.text-opacity).
+     */
     opacity: number;
+    /**
+     * Sets the minimum zoom level (mapbox.layer.minzoom).
+     * At zoom levels less than the minzoom, the layer will be hidden.
+     */
     minzoom: number;
+    /**
+     * Sets the maximum zoom level (mapbox.layer.maxzoom).
+     * At zoom levels equal to or greater than the maxzoom, the layer will be hidden.
+     */
     maxzoom: number;
-    circle: { radius: number };
+    circle: {
+        /**
+         * Sets the circle radius (mapbox.layer.paint.circle-radius).
+         * Has an effect only when `type` is set to *circle*.
+         */
+        radius: number;
+    };
     line: Partial<ShapeLine>;
-    fill: { outlinecolor: Color };
+    fill: {
+        /**
+         * Sets the fill outline color (mapbox.layer.paint.fill-outline-color).
+         * Has an effect only when `type` is set to *fill*.
+         */
+        outlinecolor: Color;
+    };
     symbol: Partial<MapboxSymbol>;
+    /**
+     * When used in a template, named items are created in the output figure in addition to any items the figure already has in this array.
+     * You can modify these items in the output figure by making your own item with `templateitemname` matching this `name`
+     * alongside your modifications (including `visible: false` or `enabled: false` to hide it).
+     * Has no effect outside of a template.
+     */
     name: string;
+    /**
+     * Used to refer to a named item in this array in the template.
+     * Named items from the template will be created even without a matching item in the input figure,
+     * but you can modify one by making an item with `templateitemname` matching its `name`,
+     * alongside your modifications (including `visible: false` or `enabled: false` to hide it).
+     * If there is no template or no matching item,
+     * this item will be hidden unless you explicitly show it with `visible: true`.
+     */
     templateitemname: string;
 }
 
diff --git a/types/plotly.js/v2/test/index-tests.ts b/types/plotly.js/v2/test/index-tests.ts
