diff --git a/docs/api-reference/geolocate-control.md b/docs/api-reference/geolocate-control.md index c4c2dec4b..972413489 100644 --- a/docs/api-reference/geolocate-control.md +++ b/docs/api-reference/geolocate-control.md @@ -57,29 +57,29 @@ function App() { ### Reactive Properties -#### `style`: CSSProperties {#style} +#### `style`: CSSProperties {#style} CSS style override that applies to the control's container. ### Callbacks -#### `onGeolocate`: (evt: [GeolocateResultEvent](./types.md#geolocateresultevent)) => void {#ongeolocate} +#### `onGeolocate`: (evt: [GeolocateResultEvent](./types.md#geolocateresultevent)) => void {#ongeolocate} Called on each Geolocation API position update that returned as success. -#### `onError`: (evt: [GeolocateErrorEvent](./types.md#geolocateerrorevent)) => void {#onerror} +#### `onError`: (evt: [GeolocateErrorEvent](./types.md#geolocateerrorevent)) => void {#onerror} Called on each Geolocation API position update that returned as an error. -#### `onOutOfMaxBounds`: (evt: [GeolocateResultEvent](./types.md#geolocateresultevent)) => void {#onoutofmaxbounds} +#### `onOutOfMaxBounds`: (evt: [GeolocateResultEvent](./types.md#geolocateresultevent)) => void {#onoutofmaxbounds} Called on each Geolocation API position update that returned as success but user position is out of map `maxBounds`. -#### `onTrackUserLocationStart`: (evt: [GeolocateEvent](./types.md#geolocateevent)) => void {#ontrackuserlocationstart} +#### `onTrackUserLocationStart`: (evt: [GeolocateEvent](./types.md#geolocateevent)) => void {#ontrackuserlocationstart} Called when the GeolocateControl changes to the active lock state. -#### `onTrackUserLocationEnd`: (evt: [GeolocateEvent](./types.md#geolocateevent)) => void {#ontrackuserlocationend} +#### `onTrackUserLocationEnd`: (evt: [GeolocateEvent](./types.md#geolocateevent)) => void {#ontrackuserlocationend} Called when the GeolocateControl changes to the background state. @@ -98,7 +98,7 @@ Any options supported by the `GeolocateControl` class ([Mapbox](https://docs.map Plus the following: -#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position} +#### `position`: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' {#position} Default: `'bottom-right'` diff --git a/docs/api-reference/map.md b/docs/api-reference/map.md index ffd467685..7e5e7ac2c 100644 --- a/docs/api-reference/map.md +++ b/docs/api-reference/map.md @@ -60,17 +60,17 @@ Aside from the props listed below, the `Map` component supports all parameters o ### Layout options -#### `id`: string {#id} +#### `id`: string {#id} Map container id. -#### `style`: CSSProperties {#style} +#### `style`: CSSProperties {#style} Default: `{position: 'relative', width: '100%', height: '100%'}` Map container CSS. -#### `cursor`: string {#cursor} +#### `cursor`: string {#cursor} Default: `'auto'` @@ -78,40 +78,40 @@ The current cursor [type](https://developer.mozilla.org/en-US/docs/Web/CSS/curso ### Styling options -#### `fog`: [Fog](./types.md#fog) {#fog} +#### `fog`: [Fog](./types.md#fog) {#fog} The fog property of the style. Must conform to the [Fog Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/fog/). If `undefined` is provided, removes the fog from the map. -#### `light`: [Light](./types.md#light) {#light} +#### `light`: [Light](./types.md#light) {#light} Light properties of the style. Must conform to the [Light Style Specification](https://www.mapbox.com/mapbox-gl-style-spec/#light). -#### `mapStyle`: [MapboxStyle](./types.md#mapboxstyle) | string | Immutable {#mapstyle} +#### `mapStyle`: [MapboxStyle](./types.md#mapboxstyle) | string | Immutable {#mapstyle} Default: (empty style) The map's Mapbox style. This must be an a JSON object conforming to the schema described in the [Mapbox Style Specification](https://mapbox.com/mapbox-gl-style-spec/), or a URL to such JSON. -#### `projection`: string | [ProjectionSpecification](./types.md#projectionspecification) {#projection} +#### `projection`: string | [Projection](./types.md#projection) {#projection} Default: `'mercator'` The projection the map should be rendered in. Available projections are Albers (`'albers'`), Equal Earth (`'equalEarth'`), Equirectangular/Plate Carrée/WGS84 (`'equirectangular'`), Lambert (`'lambertConformalConic'`), Mercator (`'mercator'`), Natural Earth (`'naturalEarth'`), and Winkel Tripel (`'winkelTripel'`). Conic projections such as Albers and Lambert have configurable `center` and `parallels` properties that allow developers to define the region in which the projection has minimal distortion; see [example](https://docs.mapbox.com/mapbox-gl-js/api/map/#map#setprojection). -#### `renderWorldCopies`: boolean {#renderworldcopies} +#### `renderWorldCopies`: boolean {#renderworldcopies} Default: `true` If `true`, multiple copies of the world will be rendered, when zoomed out. -#### `styleDiffing`: boolean {#stylediffing} +#### `styleDiffing`: boolean {#stylediffing} Default: `true` Enable diffing when `mapStyle` changes. If `false`, force a 'full' update, removing the current style and building the given one instead of attempting a diff-based update. -#### `terrain`: [TerrainSpecification](./types.md#terrainspecification) {#terrain} +#### `terrain`: [Terrain](./types.md#terrain) {#terrain} Terrain property of the style. Must conform to the [Terrain Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/terrain/). If `undefined` is provided, removes terrain from the map. @@ -119,69 +119,73 @@ If `undefined` is provided, removes terrain from the map. ### Camera options -#### `initialViewState`: object {#initialviewstate} +#### `initialViewState`: object {#initialviewstate} The initial view state of the map. If specified, `longitude`, `latitude`, `zoom` etc. in props are ignored when constructing the map. Only specify `initialViewState` if `Map` is being used as an **uncontrolled component**. See [state management](../get-started/state-management.md) for examples. -- `bounds?`: [LngLatBoundsLike](./types.md#lnglatboundslike) - The initial bounds of the map. If specified, it overrides the `longitude`, `latitude` and `zoom` options. Default `null`. -- `fitBoundsOptions`: [FitBoundsOptions](./types.md#fitboundsoptions) - A `fitBounds` options object to use only when setting the `bounds` option. Default `null`. +- `bounds`: [LngLatBoundsLike](./types.md#lnglatboundslike) - The initial bounds of the map. If specified, it overrides the `longitude`, `latitude` and `zoom` options. Default `null`. +- `fitBoundsOptions` - An object to use only when setting the `bounds` option. Default `null`. + + `fitBoundsOptions.offset`: [PointLike](./types.md#pointlike) + + `fitBoundsOptions.minZoom`: number + + `fitBoundsOptions.maxZoom`: number + + `fitBoundsOptions.padding`: [PaddingOptions](./types.md#paddingoptions) - `longitude`: number - The initial longitude of the map center. Default `0`. - `latitude`: number - The initial latitude of the map center. Default `0`. - `zoom`: number - The initial zoom level. Default `0`. - `pitch`: number - The initial pitch (tilt) of the map. Default `0`. - `bearing`: number - The initial bearing (rotation) of the map. Default `0`. -#### `longitude`: number {#longitude} +#### `longitude`: number {#longitude} The longitude of the map center. -#### `latitude`: number {#latitude} +#### `latitude`: number {#latitude} The latitude of the map center. -#### `zoom`: number {#zoom} +#### `zoom`: number {#zoom} The [zoom level](https://docs.mapbox.com/help/glossary/camera/#zoom-level) of the map. -#### `pitch`: number {#pitch} +#### `pitch`: number {#pitch} The initial [pitch](https://docs.mapbox.com/help/glossary/camera/#pitch) (tilt) of the map, measured in degrees away from the plane of the screen (0-85). -#### `bearing`: number {#bearing} +#### `bearing`: number {#bearing} The initial [bearing](https://docs.mapbox.com/help/glossary/camera/#bearing) (rotation) of the map, measured in degrees counter-clockwise from north. -#### `padding`: [PaddingOptions](./types.md#paddingoptions) {#padding} +#### `padding`: [PaddingOptions](./types.md#paddingoptions) {#padding} Default: `null` The padding in pixels around the viewport. -#### `minZoom`: number {#minzoom} +#### `minZoom`: number {#minzoom} Default: `0` The minimum zoom level of the map (0-24). -#### `maxZoom`: number {#maxzoom} +#### `maxZoom`: number {#maxzoom} Default: `22` The maximum zoom level of the map (0-24). -#### `minPitch`: number {#minpitch} +#### `minPitch`: number {#minpitch} Default: `0` The minimum pitch of the map (0-85). -#### `maxPitch`: number {#maxpitch} +#### `maxPitch`: number {#maxpitch} Default: `60` The maximum pitch of the map (0-85). -#### `maxBounds`: [LngLatBoundsLike](./types.md#lnglatboundslike) {#maxbounds} +#### `maxBounds`: [LngLatBoundsLike](./types.md#lnglatboundslike) {#maxbounds} Default: `null` @@ -189,55 +193,56 @@ If set, the map is constrained to the given bounds. ### Input handler options -#### `boxZoom`: boolean {#boxzoom} +#### `boxZoom`: boolean {#boxzoom} Default: `true` -If `true`, the "box zoom" interaction is enabled (see [BoxZoomHandler](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#boxzoomhandler)). +If `true`, the "box zoom" interaction is enabled. See `BoxZoomHandler` +([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#boxzoomhandler) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.BoxZoomHandler/)) -#### `doubleClickZoom`: boolean {#doubleclickzoom} +#### `doubleClickZoom`: boolean {#doubleclickzoom} Default: `true` -If `true`, the "double click to zoom" interaction is enabled (see [DoubleClickZoomHandler](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#doubleclickzoomhandler)). +If `true`, the "double click to zoom" interaction is enabled. See `DoubleClickZoomHandler` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#doubleclickzoomhandler) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.DoubleClickZoomHandler/)). -#### `dragRotate`: boolean {#dragrotate} +#### `dragRotate`: boolean {#dragrotate} Default: `true` -If `true`, the "drag to rotate" interaction is enabled (see [DragRotateHandler](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#dragrotatehandler)). +If `true`, the "drag to rotate" interaction is enabled. See `DragRotateHandler` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#dragrotatehandler) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.DragRotateHandler/)). -#### `dragPan`: boolean | [DragPanOptions](./types.md#dragpanoptions) {#dragpan} +#### `dragPan`: boolean | Object {#dragpan} Default: `true` -If `true`, the "drag to pan" interaction is enabled. Optionally accpt an object value that is the options to [DragPanHandler#enable](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#dragpanhandler). +If `true`, the "drag to pan" interaction is enabled. Optionally accpt an object value that is the options to `DragPanHandler.enable` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#dragpanhandler#enable) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.DragPanHandler/#enable)). -#### `keyboard`: boolean {#keyboard} +#### `keyboard`: boolean {#keyboard} Default: `true` -If `true`, keyboard shortcuts are enabled (see [KeyboardHandler](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#keyboardhandler)). +If `true`, keyboard shortcuts are enabled. See `KeyboardHandler` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#keyboardhandler) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.KeyboardHandler/)). -#### `scrollZoom`: boolean | [ZoomRotateOptions](./types.md#zoomrotateoptions) {#scrollzoom} +#### `scrollZoom`: boolean | Object {#scrollzoom} Default: `true` -If `true`, the "scroll to zoom" interaction is enabled. Optionally accpt an object value that is the options to [ScrollZoomHandler#enable](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#scrollzoomhandler). +If `true`, the "scroll to zoom" interaction is enabled. Optionally accpt an object value that is the options to `ScrollZoomHandler.enable` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#scrollzoomhandler#enable) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.ScrollZoomHandler/#enable)) -#### `touchPitch`: boolean {#touchpitch} +#### `touchPitch`: boolean | Object {#touchpitch} Default: `true` -If `true`, the "drag to pitch" interaction is enabled. Optionally accpt an object value that is the options to [TouchPitchHandler#enable](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#touchpitchhandler). +If `true`, the "drag to pitch" interaction is enabled. Optionally accpt an object value that is the options to `TouchPitchHandler.enable`([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#touchpitchhandler) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.TwoFingersTouchPitchHandler/#enable)). -#### `touchZoomRotate`: boolean | [ZoomRotateOptions](./types.md#zoomrotateoptions) {#touchzoomrotate} +#### `touchZoomRotate`: boolean | Object {#touchzoomrotate} Default: `true` -If `true`, the "pinch to rotate and zoom" interaction is enabled. Optionally accpt an object value that is the options to [TouchZoomRotateHandler#enable](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#touchzoomrotatehandler). +If `true`, the "pinch to rotate and zoom" interaction is enabled. Optionally accpt an object value that is the options to `TouchZoomRotateHandler.enable` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#touchzoomrotatehandler#enable) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.TwoFingersTouchZoomHandler/#enable)). -#### `interactiveLayerIds`: string[] {#interactivelayerids} +#### `interactiveLayerIds`: string[] {#interactivelayerids} Default: `null` @@ -251,19 +256,19 @@ See the [Callbacks](#callbacks) section for affected events. ### Callbacks -#### `onResize`: (event: [MapboxEvent](./types.md#mapboxevent)) => void {#onresize} +#### `onResize`: (event: [MapEvent](./types.md#mapevent)) => void {#onresize} Called when the map has been resized. -#### `onLoad`: (event: [MapboxEvent](./types.md#mapboxevent)) => void {#onload} +#### `onLoad`: (event: [MapEvent](./types.md#mapevent)) => void {#onload} Called after all necessary resources have been downloaded and the first visually complete rendering of the map has occurred. -#### `onRender`: (event: [MapboxEvent](./types.md#mapboxevent)) => void {#onrender} +#### `onRender`: (event: [MapEvent](./types.md#mapevent))) => void {#onrender} Called whenever the map is drawn to the screen. -#### `onIdle`: (event: [MapboxEvent](./types.md#mapboxevent)) => void {#onidle} +#### `onIdle`: (event: [MapEvent](./types.md#mapevent))) => void {#onidle} Called after the last frame rendered before the map enters an "idle" state: @@ -271,186 +276,186 @@ Called after the last frame rendered before the map enters an "idle" state: - All currently requested tiles have loaded - All fade/transition animations have completed -#### `onRemove`: (event: [MapboxEvent](./types.md#mapboxevent)) => void {#onremove} +#### `onRemove`: (event: [MapEvent](./types.md#mapevent))) => void {#onremove} Called when the map has been removed. -#### `onError`: (event: [ErrorEvent](./types.md#errorevent)) => void {#onerror} +#### `onError`: (event: [ErrorEvent](./types.md#errorevent)) => void {#onerror} Default: `evt => console.error(evt.error)` Called when an error occurs. -#### `onMouseDown`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmousedown} +#### `onMouseDown`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmousedown} Called when a pointing device (usually a mouse) is pressed within the map. If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. -#### `onMouseUp`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseup} +#### `onMouseUp`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseup} Called when a pointing device (usually a mouse) is released within the map. If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. -#### `onMouseOver`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseover} +#### `onMouseOver`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseover} Called when a pointing device (usually a mouse) is moved within the map. As you move the cursor across a web page containing a map, the event will fire each time it enters the map or any child elements. -#### `onMouseEnter`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseenter} +#### `onMouseEnter`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseenter} Called when a pointing device (usually a mouse) enters a visible portion of the layer(s) specified by `interactiveLayerIds` from outside that layer or outside the map canvas. -#### `onMouseMove`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmousemove} +#### `onMouseMove`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmousemove} Called when a pointing device (usually a mouse) is moved while the cursor is inside the map. As you move the cursor across the map, the event will fire every time the cursor changes position within the map. If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. -#### `onMouseLeave`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseleave} +#### `onMouseLeave`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseleave} Called when a pointing device (usually a mouse) leaves a visible portion of the layer(s) specified by `interactiveLayerIds` or moves from the layer to outside the map canvas. -#### `onMouseOut`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseout} +#### `onMouseOut`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onmouseout} Called when a point device (usually a mouse) leaves the map's canvas. -#### `onClick`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onclick} +#### `onClick`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#onclick} Called when a pointing device (usually a mouse) is pressed and released at the same point on the map. If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. -#### `onDblClick`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#ondblclick} +#### `onDblClick`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#ondblclick} Called when a pointing device (usually a mouse) is pressed and released twice at the same point on the map in rapid succession. If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. -#### `onContextMenu`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#oncontextmenu} +#### `onContextMenu`: (event: [MapLayerMouseEvent](./types.md#maplayermouseevent)) => void {#oncontextmenu} Called when the right button of the mouse is clicked or the context menu key is pressed within the map. If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. -#### `onWheel`: (event: [MapWheelEvent](./types.md#mapwheelevent)) => void {#onwheel} +#### `onWheel`: (event: [MapWheelEvent](./types.md#mapwheelevent)) => void {#onwheel} Called when a wheel event occurs within the map. -#### `onTouchStart`: (event: [MapLayerTouchEvent](./types.md#maplayertouchevent)) => void {#ontouchstart} +#### `onTouchStart`: (event: [MapLayerTouchEvent](./types.md#maplayertouchevent)) => void {#ontouchstart} Called when a `touchstart` event occurs within the map. If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. -#### `onTouchEnd`: (event: [MapLayerTouchEvent](./types.md#maplayertouchevent)) => void {#ontouchend} +#### `onTouchEnd`: (event: [MapLayerTouchEvent](./types.md#maplayertouchevent)) => void {#ontouchend} Called when a `touchend` event occurs within the map. If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. -#### `onTouchMove`: (event: [MapLayerTouchEvent](./types.md#maplayertouchevent)) => void {#ontouchmove} +#### `onTouchMove`: (event: [MapLayerTouchEvent](./types.md#maplayertouchevent)) => void {#ontouchmove} Called when a `touchmove` event occurs within the map. If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. -#### `onTouchCancel`: (event: [MapLayerTouchEvent](./types.md#maplayertouchevent)) => void {#ontouchcancel} +#### `onTouchCancel`: (event: [MapLayerTouchEvent](./types.md#maplayertouchevent)) => void {#ontouchcancel} Called when a `touchcancel` event occurs within the map. If `interactiveLayerIds` is specified, the event will contain an additional `features` field that contains features under the cursor from the specified layer. -#### `onMoveStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onmovestart} +#### `onMoveStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onmovestart} Called just before the map begins a transition from one view to another. -#### `onMove`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onmove} +#### `onMove`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onmove} Called repeatedly during an animated transition from one view to another. When `Map` is used as a controlled component, `event.viewState` reflects the view state that the camera "proposes" to move to, as a result of either user interaction or methods such as [flyTo](https://docs.mapbox.com/mapbox-gl-js/api/map/#map#flyto). The camera does not actually change until the application updates the view state props (`longitude`, `latitude`, `zoom` etc.). See [state management](../get-started/state-management.md) for examples. -#### `onMoveEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onmoveend} +#### `onMoveEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onmoveend} Called just after the map completes a transition from one view to another. -#### `onDragStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#ondragstart} +#### `onDragStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#ondragstart} Called when a "drag to pan" interaction starts. -#### `onDrag`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#ondrag} +#### `onDrag`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#ondrag} Called repeatedly during a "drag to pan" interaction. -#### `onDragEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#ondragend} +#### `onDragEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#ondragend} Called when a "drag to pan" interaction ends. -#### `onZoomStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onzoomstart} +#### `onZoomStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onzoomstart} Called just before the map begins a transition from one zoom level to another. -#### `onZoom`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onzoom} +#### `onZoom`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onzoom} Called repeatedly during an animated transition from one zoom level to another. When `Map` is used as a controlled component, `event.viewState.zoom` reflects the zoom that the camera "proposes" to change to, as a result of either user interaction or methods such as [flyTo](https://docs.mapbox.com/mapbox-gl-js/api/map/#map#flyto). The camera does not actually change until the application updates the `zoom` prop. -#### `onZoomEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onzoomend} +#### `onZoomEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onzoomend} Called just after the map completes a transition from one zoom level to another. -#### `onRotateStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onrotatestart} +#### `onRotateStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onrotatestart} Called just before the map begins a transition from one bearing (rotation) to another. -#### `onRotate`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onrotate} +#### `onRotate`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onrotate} Called repeatedly during an animated transition from one bearing (rotation) to another. When `Map` is used as a controlled component, `event.viewState.bearing` reflects the zoom that the camera "proposes" to change to, as a result of either user interaction or methods such as [flyTo](https://docs.mapbox.com/mapbox-gl-js/api/map/#map#flyto). The camera does not actually change until the application updates the `bearing` prop. -#### `onRotateEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onrotateend} +#### `onRotateEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onrotateend} Called just after the map completes a transition from one bearing (rotation) to another. -#### `onPitchStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onpitchstart} +#### `onPitchStart`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onpitchstart} Called just before the map begins a transition from one pitch (tilt) to another. -#### `onPitch`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onpitch} +#### `onPitch`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onpitch} Called repeatedly during an animated transition from one pitch (tilt) to another. When `Map` is used as a controlled component, `event.viewState.pitch` reflects the zoom that the camera "proposes" to change to, as a result of either user interaction or methods such as [flyTo](https://docs.mapbox.com/mapbox-gl-js/api/map/#map#flyto). The camera does not actually change until the application updates the `pitch` prop. -#### `onPitchEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onpitchend} +#### `onPitchEnd`: (event: [ViewStateChangeEvent](./types.md#viewstatechangeevent)) => void {#onpitchend} Called just after the map completes a transition from one pitch (tilt) to another. -#### `onBoxZoomStart`: (event: [MapBoxZoomEvent](./types.md#mapboxzoomevent)) => void {#onboxzoomstart} +#### `onBoxZoomStart`: (event: [MapBoxZoomEvent](./types.md#mapboxzoomevent)) => void {#onboxzoomstart} Called when a "box zoom" interaction starts. -#### `onBoxZoomEnd`: (event: [MapBoxZoomEvent](./types.md#mapboxzoomevent)) => void {#onboxzoomend} +#### `onBoxZoomEnd`: (event: [MapBoxZoomEvent](./types.md#mapboxzoomevent)) => void {#onboxzoomend} Called when a "box zoom" interaction ends. -#### `onBoxZoomCancel`: (event:[MapBoxZoomEvent](./types.md#mapboxzoomevent)) => void {#onboxzoomcancel} +#### `onBoxZoomCancel`: (event:[MapBoxZoomEvent](./types.md#mapboxzoomevent)) => void {#onboxzoomcancel} Called when the user cancels a "box zoom" interaction, or when the bounding box does not meet the minimum size threshold. -#### `onData`: (event: [MapStyleDataEvent](./types.md#mapstyledataevent) | [MapSourceDataEvent](./types.md#mapsourcedataevent)) => void {#ondata} +#### `onData`: (event: [MapStyleDataEvent](./types.md#mapstyledataevent) | [MapSourceDataEvent](./types.md#mapsourcedataevent)) => void {#ondata} Called when any map data loads or changes. See [MapDataEvent](https://docs.mapbox.com/mapbox-gl-js/api/events/#mapdataevent) for more information. -#### `onStyleData`: (event: [MapStyleDataEvent](./types.md#mapstyledataevent)) => void {#onstyledata} +#### `onStyleData`: (event: [MapStyleDataEvent](./types.md#mapstyledataevent)) => void {#onstyledata} Called when the map's style loads or changes. See [MapDataEvent](https://docs.mapbox.com/mapbox-gl-js/api/events/#mapdataevent) for more information. -#### `onSourceData`: (event: [MapSourceDataEvent](./types.md#mapsourcedataevent)) => void {#onsourcedata} +#### `onSourceData`: (event: [MapSourceDataEvent](./types.md#mapsourcedataevent)) => void {#onsourcedata} Called when one of the map's sources loads or changes, including if a tile belonging to a source loads or changes. See [MapDataEvent](https://docs.mapbox.com/mapbox-gl-js/api/events/#mapdataevent) for more information. @@ -460,7 +465,7 @@ The following props, along with any options of the `Map` class ([Mapbox](https:/ Note: props in this section are not reactive. They are only used once when the Map instance is constructed. -#### `mapLib`: any {#maplib} +#### `mapLib`: any {#maplib} Default: - `import('mapbox-gl')` if imported from `react-map-gl` @@ -507,21 +512,21 @@ function App() { ``` -#### `mapboxAccessToken`: string {#mapboxaccesstoken} +#### `mapboxAccessToken`: string {#mapboxaccesstoken} Token used to access the Mapbox data service. See [about map tokens](../get-started/mapbox-tokens.md). -#### `baseApiUrl`: string {#baseapiurl} +#### `baseApiUrl`: string {#baseapiurl} The map's default API URL for requesting tiles, styles, sprites, and glyphs. -#### `maxParallelImageRequests`: number {#maxparallelimagerequests} +#### `maxParallelImageRequests`: number {#maxparallelimagerequests} Default: `16` The maximum number of images (raster tiles, sprites, icons) to load in parallel. -#### `reuseMaps`: boolean {#reusemaps} +#### `reuseMaps`: boolean {#reusemaps} Default: `false` @@ -531,7 +536,7 @@ If `reuseMaps` is set to `true`, when a map component is unmounted, the underlyi Note that since some map options cannot be modified after initialization, when reusing maps, only the reactive props and `initialViewState` of the new component are respected. -#### `RTLTextPlugin`: string {#rtltextplugin} +#### `RTLTextPlugin`: string {#rtltextplugin} Default: `'https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-rtl-text/v0.2.3/mapbox-gl-rtl-text.js'` @@ -539,20 +544,20 @@ Sets the map's [RTL text plugin](https://www.mapbox.com/mapbox-gl-js/plugins/#ma Setting this prop is the equivelant of calling [mapboxgl.setRTLTextPlugin](https://docs.mapbox.com/mapbox-gl-js/api/properties/#setrtltextplugin) with `lazy: true`. -#### `workerClass`: object {#workerclass} +#### `workerClass`: object {#workerclass} Default: `null` Provides an interface for external module bundlers such as Webpack or Rollup to package mapbox-gl's WebWorker into a separate class and integrate it with the library. Takes precedence over `workerUrl`. -#### `workerCount`: number {#workercount} +#### `workerCount`: number {#workercount} Default: `2` The number of web workers instantiated on a page with mapbox-gl maps. -#### `workerUrl`: string {#workerurl} +#### `workerUrl`: string {#workerurl} Provides an interface for loading mapbox-gl's WebWorker bundle from a self-hosted URL. This is useful if your site needs to operate in a strict CSP (Content Security Policy) environment wherein you are not allowed to load JavaScript code from a Blob URL, which is default behavior. @@ -611,11 +616,11 @@ function App() { -The [MapRef](./types.md#mapref) object exposes [Map methods](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-instance-members) that **are safe to call without breaking the React bindings**. For example, `setStyle()` is hidden from the ref object, because the style is supposed to be changed by updating the `mapStyle` prop. Calling the method directly may cause the the React prop to mismatch with the underlying state, and lead to unexpected behaviors. +The [MapRef](./types.md#mapref) object exposes Map methods ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-instance-members) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.Map/#methods)) that **are safe to call without breaking the React bindings**. For example, `setStyle()` is hidden from the ref object, because the style is supposed to be changed by updating the `mapStyle` prop. Calling the method directly may cause the the React prop to mismatch with the underlying state, and lead to unexpected behaviors. You can still access the hidden members via `getMap()`: -#### `getMap()` {#getmap} +#### `getMap()` {#getmap} Returns the native `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js-docs/api/map/)) instance associated with this component. diff --git a/docs/api-reference/marker.md b/docs/api-reference/marker.md index f7a274354..21c90a964 100644 --- a/docs/api-reference/marker.md +++ b/docs/api-reference/marker.md @@ -63,27 +63,27 @@ If `Marker` is mounted with child components, then its content will be rendered ### Reactive Properties -#### `draggable`: boolean {#draggable} +#### `draggable`: boolean {#draggable} Default: `false` If `true`, the marker is able to be dragged to a new position on the map. -#### `latitude`: number {#latitude} +#### `latitude`: number {#latitude} Required. The latitude of the anchor location. -#### `longitude`: number {#longitude} +#### `longitude`: number {#longitude} Required. The longitude of the anchor location. -#### `offset`: [PointLike](./types.md#pointlike) {#offset} +#### `offset`: [PointLike](./types.md#pointlike) {#offset} Default: `null` The offset in pixels as a [PointLike](https://docs.mapbox.com/mapbox-gl-js/api/geography/#pointlike) object to apply relative to the element's center. Negatives indicate left and up. -#### `pitchAlignment`: 'map' | 'viewport' | 'auto' {#pitchalignment} +#### `pitchAlignment`: 'map' | 'viewport' | 'auto' {#pitchalignment} Default: `'auto'` @@ -91,17 +91,17 @@ Default: `'auto'` - `viewport` aligns the `Marker` to the plane of the viewport. - `auto` automatically matches the value of `rotationAlignment`. -#### `popup`: Popup | null {#popup} +#### `popup`: Popup | null {#popup} An instance of the `Popup` class ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#popup) | [Maplibre](https://maplibre.org/maplibre-gl-js-docs/api/markers/#popup)) to attach to this marker. If undefined or null, any popup set on this Marker instance is unset. -#### `rotation`: number {#rotation} +#### `rotation`: number {#rotation} Default: `0` The rotation angle of the marker in degrees, relative to its `rotationAlignment` setting. A positive value will rotate the marker clockwise. -#### `rotationAlignment`: 'map' | 'viewport' | 'auto' {#rotationalignment} +#### `rotationAlignment`: 'map' | 'viewport' | 'auto' {#rotationalignment} Default: `'auto'` @@ -109,25 +109,25 @@ Default: `'auto'` - `viewport` aligns the `Marker`'s rotation relative to the viewport, agnostic to map rotations. - `auto` is equivalent to `viewport`. -#### `style`: CSSProperties {#style} +#### `style`: CSSProperties {#style} CSS style override that applies to the marker's container. ### Callbacks -#### `onClick`: (evt: [MapEvent](./types.md#mapevent)) => void {#onclick} +#### `onClick`: (evt: [MapEvent](./types.md#mapevent)) => void {#onclick} Called when the marker is clicked on. -#### `onDragStart`: (evt: [MarkerDragEvent](./types.md#markerdragevent)) => void {#ondragstart} +#### `onDragStart`: (evt: [MarkerDragEvent](./types.md#markerdragevent)) => void {#ondragstart} Called when dragging starts, if `draggable` is `true`. -#### `onDrag`: (evt: [MarkerDragEvent](./types.md#markerdragevent)) => void {#ondrag} +#### `onDrag`: (evt: [MarkerDragEvent](./types.md#markerdragevent)) => void {#ondrag} Called while dragging, if `draggable` is `true`. -#### `onDragEnd`: (evt: [MarkerDragEvent](./types.md#markerdragevent)) => void {#ondragend} +#### `onDragEnd`: (evt: [MarkerDragEvent](./types.md#markerdragevent)) => void {#ondragend} Called when dragging ends, if `draggable` is `true`. diff --git a/docs/api-reference/popup.md b/docs/api-reference/popup.md index 71261af38..95e1c24ef 100644 --- a/docs/api-reference/popup.md +++ b/docs/api-reference/popup.md @@ -74,16 +74,16 @@ function App() { ### Reactive Properties -#### `anchor`: 'center' | 'left' | 'right' | 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | undefined {#anchor} +#### `anchor`: 'center' | 'left' | 'right' | 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | undefined {#anchor} A string indicating the part of the popup that should be positioned closest to the coordinate, set via `longitude` and `latitude`. If unset, the anchor will be dynamically set to ensure the popup falls within the map container with a preference for `'bottom'`. -#### `className`: string {#classname} +#### `className`: string {#classname} Space-separated CSS class names to add to popup container. -#### `offset`: number | [PointLike](./types.md#pointlike) | Record\ {#offset} +#### `offset`: number | [PointLike](./types.md#pointlike) | Record\ {#offset} Default: `null` @@ -95,23 +95,23 @@ A pixel offset applied to the popup's location specified as: Negative offsets indicate left and up. -#### `maxWidth`: string {#maxwidth} +#### `maxWidth`: string {#maxwidth} Default: `240px` A string that sets the CSS property of the popup's maximum width. -#### `style`: CSSProperties {#style} +#### `style`: CSSProperties {#style} CSS style override that applies to the popup's container. ### Callbacks -#### `onOpen`: (evt: [PopupEvent](./types.md#popupevent)) => void {#onopen} +#### `onOpen`: (evt: [PopupEvent](./types.md#popupevent)) => void {#onopen} Called when the popup is opened. -#### `onClose`: (evt: [PopupEvent](./types.md#popupevent)) => void {#onclose} +#### `onClose`: (evt: [PopupEvent](./types.md#popupevent)) => void {#onclose} Called when the popup is closed by the user clicking on the close button or outside (if `closeOnClick: true`). diff --git a/docs/api-reference/types.md b/docs/api-reference/types.md index 111f79606..68250df9d 100644 --- a/docs/api-reference/types.md +++ b/docs/api-reference/types.md @@ -4,13 +4,9 @@ The following types can be imported from `react-map-gl` when using TypeScript. ## Components -#### MapboxMap - -A [mapboxgl.Map](https://docs.mapbox.com/mapbox-gl-js/api/map/) instance. - #### IControl -A [mapboxgl.IControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#icontrol) implementation. +A [custom control implementation](https://docs.mapbox.com/mapbox-gl-js/api/markers/#icontrol). #### CustomLayerInterface @@ -20,14 +16,10 @@ A [custom layer implementation](https://docs.mapbox.com/mapbox-gl-js/api/#custom Instance [ref](https://reactjs.org/docs/refs-and-the-dom.html#creating-refs) of a `Map` component. See [Map documentation](./map.md#methods) for details. -#### GeolocateControlRef - -Instance [ref](https://reactjs.org/docs/refs-and-the-dom.html#creating-refs) of a `GeolocateControl` component. See [GeolocateControl documentation](./geolocate-control.md#methods) for details. - ## Styling -#### MapboxStyle +#### MapStyle An object conforming to the [Mapbox Style Specification](https://mapbox.com/mapbox-gl-style-spec/). @@ -39,17 +31,13 @@ An object conforming to the [Fog Style Specification](https://docs.mapbox.com/ma An object conforming to the [Light Style Specification](https://www.mapbox.com/mapbox-gl-style-spec/#light). -#### TerrainSpecification +#### Terrain An object conforming to the [Terrain Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/terrain/). -#### ProjectionSpecification +#### Projection -An object with the following fields: - -- `name` (string): projection name, one of Albers (`'albers'`), Equal Earth (`'equalEarth'`), Equirectangular/Plate Carrée/WGS84 (`'equirectangular'`), Lambert (`'lambertConformalConic'`), Mercator (`'mercator'`), Natural Earth (`'naturalEarth'`), and Winkel Tripel (`'winkelTripel'`). -- `center?` ([number, number]): longitude and latitude of the projection center -- `parallels?` ([number, number]): the [two standard parallels](https://en.wikipedia.org/wiki/Map_projection#Conic) of a conic projection such as Albers and Lambert. +An object conforming to the [Projection Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/projection/). #### BackgroundLayer @@ -122,48 +110,10 @@ A JSON object that defines a `canvas` source type. See [CanvasSourceOptions](htt ## Configurations -#### Anchor - -One of `'center'`, `'left'`, `'right'`, `'top'`, `'bottom'`, `'top-left'`, `'top-right'`, `'bottom-left'` and `'bottom-right'`. - -#### Alignment - -One of `'map'`, `'viewport'` and `'auto'`. - #### ControlPosition One of `'top-right'`, `'top-left'`, `'bottom-right'` and `'bottom-left'`. -#### DragPanOptions - -An object with the following fields: - -- `linearity?`: number - The rate at which the speed reduces after the pan ends. -- `easing?`: (t: number) => number - Optional easing function when applying the drag. Defaults to bezier function. -- `deceleration?`: number - Factor used to scale the drag velocity. Default `0`. -- `maxSpeed?`: number - The maximum value of the drag velocity. Default `1400`. - -See [DragPanHandler#enable](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#dragpanhandler#enable). - -#### FitBoundsOptions - -An object with the following fields: - -- `offset?`: [PointLike](#pointlike) - The center of the given bounds relative to the map's center, measured in pixels. -- `padding?`: [PaddingOptions](#paddingoptions) - The amount of padding in pixels to add to the given bounds. -- `maxZoom?`: number - The maximum zoom level to allow when the map fits to the specified bounds. -- `maxZoom?`: number - The minimum zoom level to allow when the map fits to the specified bounds. - -See [Map#fitBounds](https://docs.mapbox.com/mapbox-gl-js/api/map/#map#fitbounds) - -#### ZoomRotateOptions - -An object with the following fields: - -- `around?`: 'center' - If "center" is passed, map will zoom around center of map. - -See [ScrollZoomHandler#enable](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#scrollzoomhandler#enable), [TouchZoomRotateHandler#enable](https://docs.mapbox.com/mapbox-gl-js/api/handlers/#touchzoomrotatehandler#enable) - #### PaddingOptions An object with the following fields: @@ -173,22 +123,6 @@ An object with the following fields: - `right`: number - in pixels. - `bottom`: number - in pixels. -#### TransformRequestFunction - -A function that takes the following arguments: - -- `url`: string -- `resourceType`: 'Unknown' | 'Style' | 'Source' | 'Tile' | 'Glyphs' | 'SpriteImage' | 'SpriteJSON' | 'Image'; - -And returns an object with the following fields: - -- `url`: string - The URL to be requested. -- `credentials?`: 'same-origin' | 'include' - Use `'include'` to send cookies with cross-origin requests. -- `headers?`: { [header: string]: any } - The headers to be sent with the request. -- `method?`: 'GET' | 'POST' | 'PUT' -- `collectResourceTiming?`: boolean - -See [RequestParameters](https://docs.mapbox.com/mapbox-gl-js/api/properties/#requestparameters). ## Data Types @@ -216,7 +150,7 @@ A [mapboxgl.Point](https://github.com/mapbox/point-geometry) object. A [Point](#point) or an array of two numbers representing x and y screen coordinates in pixels. -#### MapboxGeoJSONFeature +#### MapGeoJSONFeature A [GeoJSON](http://geojson.org/) feature that also contains the following library-specific fields: @@ -237,36 +171,36 @@ An object with the following fields: ## Sources -The following are implementations of source types that could be retrieved with [Map#getSource](https://docs.mapbox.com/mapbox-gl-js/api/map/#map#getsource). +The following are implementations of source types that could be retrieved with `Map.getSource` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/#map#getsource) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.Map/#getsource)). #### GeoJSONSource -A source containing GeoJSON. See [GeoJSONSource](https://docs.mapbox.com/mapbox-gl-js/api/sources/#geojsonsource). +A source containing GeoJSON. See `GeoJSONSource` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/sources/#geojsonsource) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.GeoJSONSource/)). #### VideoSource -A source containing video. See [VideoSource](https://docs.mapbox.com/mapbox-gl-js/api/sources/#videosource). +A source containing video. See `VideoSource` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/sources/#videosource) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.VideoSource/)). #### ImageSource -A source containing image. See [ImageSource](https://docs.mapbox.com/mapbox-gl-js/api/sources/#imagesource). +A source containing image. See `ImageSource` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/sources/#imagesource) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.ImageSource/)). #### CanvasSource -A source containing the contents of an HTML canvas. See [CanvasSource](https://docs.mapbox.com/mapbox-gl-js/api/sources/#canvassource). +A source containing the contents of an HTML canvas. See `CanvasSource`([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/sources/#canvassource) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.CanvasSource/)). #### VectorTileSource -A source containing vector tiles in [Mapbox Vector Tile format](https://docs.mapbox.com/vector-tiles/reference/). See [VectorTileSource](https://docs.mapbox.com/mapbox-gl-js/api/sources/#vectortilesource). +A source containing vector tiles in [Mapbox Vector Tile format](https://docs.mapbox.com/vector-tiles/reference/). See `VectorTileSource` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/sources/#vectortilesource) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.VectorTileSource/)). ## Events -#### MapboxEvent +#### MapEvent An object with the following fields: - `type`: string - Event type -- `target`: [MapboxMap](#mapboxmap) - The map instance that fired the event +- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js-docs/api/map/)) - `originalEvent?`: [Event](https://developer.mozilla.org/en-US/docs/Web/API/Event) #### MapLayerMouseEvent @@ -274,20 +208,20 @@ An object with the following fields: An object with the following fields: - `type`: string -- `target`: [MapboxMap](#mapboxmap) +- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js-docs/api/map/)) - `originalEvent?`: [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) - `point`: [Point](#point) - `lngLat`: [LngLat](#lnglat) - `preventDefault`: () => void - `defaultPrevented`: boolean -- `features?`: [MapboxGeoJSONFeature](#mapboxgeojsonfeature)[] +- `features?`: [MapGeoJSONFeature](#mapgeojsonfeature)[] #### MapWheelEvent An object with the following fields: - `type`: string -- `target`: [MapboxMap](#mapboxmap) +- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js-docs/api/map/)) - `originalEvent?`: [WheelEvent](https://developer.mozilla.org/en-US/docs/Web/API/WheelEvent) - `preventDefault`: () => void - `defaultPrevented`: boolean @@ -297,7 +231,7 @@ An object with the following fields: An object with the following fields: - `type`: string -- `target`: [MapboxMap](#mapboxmap) +- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js-docs/api/map/)) - `originalEvent?`: [TouchEvent](https://developer.mozilla.org/en-US/docs/Web/API/TouchEvent) - `point`: [Point](#point) - `lngLat`: [LngLat](#lnglat) @@ -305,14 +239,14 @@ An object with the following fields: - `lngLats`: [LngLat](#lnglat)[] - `preventDefault`: () => void - `defaultPrevented`: boolean -- `features?`: [MapboxGeoJSONFeature](#mapboxgeojsonfeature)[] +- `features?`: [MapGeoJSONFeature](#mapgeojsonfeature)[] #### ViewStateChangeEvent An object with the following fields: - `type`: string - Event type -- `target`: [MapboxMap](#mapboxmap) +- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js-docs/api/map/)) - `viewState`: [ViewState](#viewstate) - the next view state that the camera wants to change to based on user input or transition. #### MapBoxZoomEvent @@ -320,7 +254,7 @@ An object with the following fields: An object with the following fields: - `type`: string -- `target`: [MapboxMap](#mapboxmap) +- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js-docs/api/map/)) - `originalEvent?`: [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) - `boxZoomBounds`: [LngLatBounds](#lnglatbounds) @@ -329,7 +263,7 @@ An object with the following fields: An object with the following fields: - `type`: string -- `target`: [MapboxMap](#mapboxmap) +- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js-docs/api/map/)) - `dataType`: 'style' #### MapSourceDataEvent @@ -337,7 +271,7 @@ An object with the following fields: An object with the following fields: - `type`: string -- `target`: [MapboxMap](#mapboxmap) +- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js-docs/api/map/)) - `dataType`: 'source' - `isSourceLoaded`: boolean - `source`: string @@ -353,6 +287,7 @@ See [MapDataEvent](https://docs.mapbox.com/mapbox-gl-js/api/events/#mapdataevent An object with the following fields: - `type`: 'error' +- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js-docs/api/map/)) - `error`: [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) #### GeolocateEvent @@ -360,15 +295,15 @@ An object with the following fields: An object with the following fields: - `type`: string -- `target`: [MapboxMap](#mapboxmap) -- `target`: [mapboxgl.GeolocateControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#geolocatecontrol) +- `target`: `Map` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/map/) | [Maplibre](https://maplibre.org/maplibre-gl-js-docs/api/map/)) +- `target`: `GeolocateControl` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#geolocatecontrol) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.GeolocateControl/)) #### GeolocateResultEvent An object with the following fields: - `type`: string -- `target`: [mapboxgl.GeolocateControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#geolocatecontrol) +- `target`: `GeolocateControl` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#geolocatecontrol) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.GeolocateControl/)) - `coords`: [GeolocationCoordinates](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationCoordinates) - the current location. - `timestamp`: number - the time at which the location was retrieved. @@ -377,16 +312,23 @@ An object with the following fields: An object with the following fields: - `type`: string -- `target`: [mapboxgl.GeolocateControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#geolocatecontrol) +- `target`: `GeolocateControl` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#geolocatecontrol) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.GeolocateControl/)) - `code`: PERMISSION_DENIED | POSITION_UNAVAILABLE | TIMEOUT - see [GeolocationPositionError](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationPositionError) - `message`: string - the details of the error. Specifications note that this is primarily intended for debugging use and not to be shown directly in a user interface. +#### MarkerEvent + +An object with the following fields: + +- `type`: string +- `target`: `Marker` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#marker) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.Marker/)) + #### MarkerDragEvent An object with the following fields: - `type`: string -- `target`: [mapboxgl.Marker](https://docs.mapbox.com/mapbox-gl-js/api/markers/#marker) +- `target`: `Marker` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#marker) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.Marker/)) - `lngLat`: [LngLat](#lnglat) - the new location of the marker #### PopupEvent @@ -394,4 +336,4 @@ An object with the following fields: An object with the following fields: - `type`: string -- `target`: [mapboxgl.Popup](https://docs.mapbox.com/mapbox-gl-js/api/markers/#popup) +- `target`: `Popup` ([Mapbox](https://docs.mapbox.com/mapbox-gl-js/api/markers/#popup) | [Maplibre](https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.Popup/)) diff --git a/src/components/source.ts b/src/components/source.ts index 28382aa83..38ae76e8f 100644 --- a/src/components/source.ts +++ b/src/components/source.ts @@ -13,7 +13,7 @@ import type { ImageSourceImplemtation, AnySourceImplementation } from '../types'; -import type {GeoJSONSource, ImageSource, VectorSource} from '../types/style-spec-maplibre'; +import type {GeoJSONSourceRaw, ImageSourceRaw, VectorSourceRaw} from '../types/style-spec-maplibre'; export type SourceProps = (SourceT | CustomSource) & { id?: string; @@ -66,25 +66,25 @@ function updateSource( if (type === 'geojson') { (source as GeoJSONSourceImplementation).setData( - (props as unknown as GeoJSONSource).data as any + (props as unknown as GeoJSONSourceRaw).data as any ); } else if (type === 'image') { (source as ImageSourceImplemtation).updateImage({ - url: (props as unknown as ImageSource).url, - coordinates: (props as unknown as ImageSource).coordinates + url: (props as unknown as ImageSourceRaw).url, + coordinates: (props as unknown as ImageSourceRaw).coordinates }); } else if ('setCoordinates' in source && changedKeyCount === 1 && changedKey === 'coordinates') { - source.setCoordinates((props as ImageSource).coordinates); + source.setCoordinates((props as ImageSourceRaw).coordinates); } else if ('setUrl' in source) { // Added in 1.12.0: // vectorTileSource.setTiles // vectorTileSource.setUrl switch (changedKey) { case 'url': - source.setUrl((props as VectorSource).url); + source.setUrl((props as VectorSourceRaw).url); break; case 'tiles': - source.setTiles((props as VectorSource).tiles); + source.setTiles((props as VectorSourceRaw).tiles); break; default: } diff --git a/src/exports-mapbox.ts b/src/exports-mapbox.ts index b1a1e0e20..64d5d7373 100644 --- a/src/exports-mapbox.ts +++ b/src/exports-mapbox.ts @@ -12,7 +12,7 @@ import type { NavigationControl as MapboxNavigationControl, ScaleControl as MapboxScaleControl } from 'mapbox-gl'; -import {MapboxStyle, AnyLayer, AnySource} from './types/style-spec-mapbox'; +import {MapStyle, AnyLayer, AnySource} from './types/style-spec-mapbox'; import {default as _Map, MapProps as _MapProps} from './components/map'; import {default as _Marker, MarkerProps as _MarkerProps} from './components/marker'; @@ -48,12 +48,12 @@ export function useMap() { return _useMap(); } -export type MapProps = _MapProps; +export type MapProps = _MapProps; export type MapRef = _MapRef; const mapLib = import('mapbox-gl'); export const Map = (() => { return React.forwardRef(function Map(props: MapProps, ref: React.Ref) { - return _Map(props, ref, mapLib); + return _Map(props, ref, mapLib); }); })(); @@ -113,6 +113,21 @@ export default Map; // Types export * from './types/public'; +export type { + Point, + PointLike, + LngLat, + LngLatLike, + LngLatBounds, + LngLatBoundsLike, + PaddingOptions, + MapboxGeoJSONFeature as MapGeoJSONFeature, + GeoJSONSource, + VideoSource, + ImageSource, + CanvasSource, + VectorSourceImpl as VectorTileSource +} from 'mapbox-gl'; export * from './types/style-spec-mapbox'; // Events @@ -135,3 +150,10 @@ export type MarkerDragEvent = events.MarkerDragEvent; export type GeolocateEvent = events.GeolocateEvent; export type GeolocateResultEvent = events.GeolocateResultEvent; export type GeolocateErrorEvent = events.GeolocateErrorEvent; + +// v7.0 backward compatibility + +/** @deprecated use `MapStyle` */ +export type MapboxStyle = MapStyle; + +export type {Map as MapboxMap, MapboxEvent, MapboxGeoJSONFeature} from 'mapbox-gl'; diff --git a/src/exports-maplibre.ts b/src/exports-maplibre.ts index 9c43df769..df042bff7 100644 --- a/src/exports-maplibre.ts +++ b/src/exports-maplibre.ts @@ -12,7 +12,7 @@ import type { NavigationControl as MaplibreNavigationControl, ScaleControl as MaplibreScaleControl } from 'maplibre-gl'; -import {MapboxStyle, AnyLayer, AnySource} from './types/style-spec-maplibre'; +import {MapStyle, AnyLayer, AnySource} from './types/style-spec-maplibre'; import {default as _Map, MapProps as _MapProps} from './components/map'; import {default as _Marker, MarkerProps as _MarkerProps} from './components/marker'; @@ -48,12 +48,12 @@ export function useMap() { return _useMap(); } -export type MapProps = _MapProps; +export type MapProps = _MapProps; export type MapRef = _MapRef; const mapLib = import('maplibre-gl'); export const Map = (() => { return React.forwardRef(function Map(props: MapProps, ref: React.Ref) { - return _Map(props, ref, mapLib); + return _Map(props, ref, mapLib); }); })(); @@ -113,6 +113,21 @@ export default Map; // Types export * from './types/public'; +export type {default as Point} from '@mapbox/point-geometry'; +export type { + PointLike, + LngLat, + LngLatLike, + LngLatBounds, + LngLatBoundsLike, + PaddingOptions, + MapGeoJSONFeature, + GeoJSONSource, + VideoSource, + ImageSource, + CanvasSource, + VectorTileSource +} from 'maplibre-gl'; export * from './types/style-spec-maplibre'; // Events diff --git a/src/types/common.ts b/src/types/common.ts index 3c4a2a95c..a44414c12 100644 --- a/src/types/common.ts +++ b/src/types/common.ts @@ -1,6 +1,6 @@ import type GeoJSON from 'geojson'; -/* Data types */ +/* Data types that are compatible with both mapbox and maplibre. Not exposed to the end user. */ /** @mapbox/point-geometry */ export interface Point { @@ -55,18 +55,12 @@ export type LngLatBoundsLike = | [number, number, number, number] | LngLatLike; -export type Anchor = - | 'center' - | 'left' - | 'right' - | 'top' - | 'bottom' - | 'top-left' - | 'top-right' - | 'bottom-left' - | 'bottom-right'; - -export type Alignment = 'map' | 'viewport' | 'auto'; +export type MapGeoJSONFeature = GeoJSON.Feature & { + layer: any; + source: string; + sourceLayer: string; + state: {[key: string]: any}; +}; export type PaddingOptions = { top: number; @@ -75,6 +69,8 @@ export type PaddingOptions = { right: number; }; +/* Public */ + /** Describes the camera's state */ export type ViewState = { /** Longitude at map center */ @@ -96,10 +92,3 @@ export type ControlPosition = 'top-right' | 'top-left' | 'bottom-right' | 'botto export interface ImmutableLike { toJS: () => T; } - -export type MapGeoJSONFeature = GeoJSON.Feature & { - layer: any; - source: string; - sourceLayer: string; - state: {[key: string]: any}; -}; diff --git a/src/types/index.ts b/src/types/index.ts index 0c4cc09e1..618d31a03 100644 --- a/src/types/index.ts +++ b/src/types/index.ts @@ -1,4 +1,5 @@ -export * from './public'; +export * from './common'; +export * from './lib'; export * from './events'; import type GeoJSON from 'geojson'; diff --git a/src/types/lib.ts b/src/types/lib.ts index 4a130f97c..ef2d6aa5d 100644 --- a/src/types/lib.ts +++ b/src/types/lib.ts @@ -1,4 +1,4 @@ -import type {PaddingOptions, LngLat, Point, LngLatLike, PointLike} from './common'; +import type {PaddingOptions, LngLat, Point, LngLatLike, PointLike, ControlPosition} from './common'; export interface IControl { onAdd(map: MapT): HTMLElement; @@ -27,10 +27,7 @@ export interface MapInstance extends Evented { // https://github.com/mapbox/mapbox-gl-js/issues/6522 fire(type: string, properties?: {[key: string]: any}); - addControl( - control: IControl, - position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' - ); + addControl(control: IControl, position?: ControlPosition); removeControl(control: IControl); diff --git a/src/types/public.ts b/src/types/public.ts index 439e8e5f3..a3e02dba0 100644 --- a/src/types/public.ts +++ b/src/types/public.ts @@ -1,2 +1,9 @@ -export * from './common'; -export * from './lib'; +export type {ViewState, ControlPosition} from './common'; +export type { + IControl, + MapInstance, + MapLib, + CustomLayerInterface, + CustomSource, + CustomSourceImplementation +} from './lib'; diff --git a/src/types/style-spec-mapbox.ts b/src/types/style-spec-mapbox.ts index 778a48b9f..d8b40737c 100644 --- a/src/types/style-spec-mapbox.ts +++ b/src/types/style-spec-mapbox.ts @@ -42,37 +42,37 @@ export type { // Sources import type { - GeoJSONSourceRaw as GeoJSONSource, - VideoSourceRaw as VideoSource, - ImageSourceRaw as ImageSource, - VectorSource, + GeoJSONSourceRaw, + VideoSourceRaw, + ImageSourceRaw, + VectorSource as VectorSourceRaw, RasterSource, - CanvasSourceRaw as CanvasSource, + CanvasSourceRaw, RasterDemSource } from 'mapbox-gl'; export type AnySource = - | GeoJSONSource - | VideoSource - | ImageSource - | CanvasSource - | VectorSource + | GeoJSONSourceRaw + | VideoSourceRaw + | ImageSourceRaw + | CanvasSourceRaw + | VectorSourceRaw | RasterSource | RasterDemSource; export type { - GeoJSONSource, - VideoSource, - ImageSource, - CanvasSource, - VectorSource, + GeoJSONSourceRaw, + VideoSourceRaw, + ImageSourceRaw, + CanvasSourceRaw, + VectorSourceRaw, RasterSource, RasterDemSource }; // Other export type { - Style as MapboxStyle, + Style as MapStyle, Light, Fog, TerrainSpecification as Terrain, diff --git a/src/types/style-spec-maplibre.ts b/src/types/style-spec-maplibre.ts index 7bf412dc0..672eb8e32 100644 --- a/src/types/style-spec-maplibre.ts +++ b/src/types/style-spec-maplibre.ts @@ -12,14 +12,16 @@ import type { LineLayerSpecification as LineLayer, RasterLayerSpecification as RasterLayer, SymbolLayerSpecification as SymbolLayer, - GeoJSONSourceSpecification as GeoJSONSource, - VideoSourceSpecification as VideoSource, - ImageSourceSpecification as ImageSource, - VectorSourceSpecification as VectorSource, + GeoJSONSourceSpecification as GeoJSONSourceRaw, + VideoSourceSpecification as VideoSourceRaw, + ImageSourceSpecification as ImageSourceRaw, + VectorSourceSpecification as VectorSourceRaw, RasterSourceSpecification as RasterSource, RasterDEMSourceSpecification as RasterDemSource } from '@maplibre/maplibre-gl-style-spec'; +import {CanvasSourceSpecification as CanvasSourceRaw} from 'maplibre-gl'; + // Layers export type { BackgroundLayer, @@ -45,29 +47,29 @@ export type AnyLayer = | SymbolLayer; // Sources -export {GeoJSONSource, VideoSource, ImageSource, VectorSource, RasterSource, RasterDemSource}; - -// Not part of the style spec but a valid source -export interface CanvasSource { - type: 'canvas'; - coordinates: number[][]; - animate?: boolean; - canvas: string | HTMLCanvasElement; -} +export { + GeoJSONSourceRaw, + VideoSourceRaw, + ImageSourceRaw, + CanvasSourceRaw, + VectorSourceRaw, + RasterSource, + RasterDemSource +}; export type AnySource = - | GeoJSONSource - | VideoSource - | ImageSource - | VectorSource + | GeoJSONSourceRaw + | VideoSourceRaw + | ImageSourceRaw + | CanvasSourceRaw + | VectorSourceRaw | RasterSource - | RasterDemSource - | CanvasSource; + | RasterDemSource; // Other style types export type { - StyleSpecification as MapboxStyle, + StyleSpecification as MapStyle, LightSpecification as Light, TerrainSpecification as Terrain } from '@maplibre/maplibre-gl-style-spec';