React-map-gl: TypeScript definition file?

[rimig]

Any known typings file for using react-map-gl with TypeScript? For a library this popular, I assumed one would exist but not finding one in @types.

[fnberta]

I have a work in progress file that I'm using in a project. Would the project be open to accept a PR for this once it's polished?

[Pessimistress]

@fnberta Yes of course. Unfortunately I'm not familiar with TypeScript myself. Does it make sense if your PR adds a example to the examples folder with full TypeScript setup?

[fnberta]

I don't think we need an example, it should just work with TS once the definition file is included. Will make a PR once it's ready.

[rimig]

Hey @fnberta , glad to hear you have something as well. It might be worth contributing it to the @types org via http://definitelytyped.org/ ? I think that's preferred if the project itself is not in Typescript.

Happy to help fill it in if you have one. Here's what I've been using but it's not fully up-to-date and is missing some of the API. I can also push this one to get us started, no preference, just wanted to start the initiative.

// tslint:disable:max-classes-per-file
// tslint:disable:no-namespace

declare namespace ReactMapGL {
    export interface IViewport {
        bearing: number;
        isDragging: boolean;
        latitude: number;
        longitude: number;
        pitch?: number;
        startBearing?: number;
        startDragLngLat?: number[];
        startPitch?: number;
        zoom: number;
    }

    interface IStaticMapProps {
        /** Mapbox API access token for mapbox-gl-js. Required when using Mapbox vector tiles/styles. */
        mapboxApiAccessToken: string;
        /** Mapbox WebGL context creation option. Useful when you want to export the canvas as a PNG. */
        preserveDrawingBuffer?: boolean;
        /** Show attribution control or not. */
        attributionControl?: boolean;

        /** The Mapbox style. A string url or a MapboxGL style Immutable.Map object. */
        mapStyle?: string; // TODO can also be immutable map
        /** There are known issues with style diffing. As stopgap, add option to prevent style diffing. */
        preventStyleDiffing?: boolean;
        /** Whether the map is visible */
        visible?: boolean;

        /** The width of the map. */
        width: number;
        /** The height of the map. */
        height: number;
        /** The longitude of the center of the map. */
        longitude: number;
        /** The latitude of the center of the map. */
        latitude: number;
        /** The tile zoom level of the map. */
        zoom: number;
        /** Specify the bearing of the viewport */
        bearing?: number;
        /** Specify the pitch of the viewport */
        pitch?: number;
        /** Altitude of the viewport camera. Default 1.5 "screen heights" */
        altitude?: number; // Note: Non-public API, see https://github.com/mapbox/mapbox-gl-js/issues/1137

        perspectiveEnabled?: boolean;

    }

    interface IInteractiveMapProps extends IStaticMapProps {
        /** Max zoom level */
        maxZoom?: number;
        /** Min zoom level */
        minZoom?: number;
        /** Max pitch in degrees */
        maxPitch?: number;
        /** Min pitch in degrees */
        minPitch?: number;

        /**
         * `onViewportChange` callback is fired when the user interacted with the
         * map. The object passed to the callback contains viewport properties
         * such as `longitude`, `latitude`, `zoom` etc.
         */
        onViewportChange?: (viewport: IViewport) => void;

        /** Scroll to zoom */
        scrollZoom?: boolean;
        /** Drag to pan */
        dragPan?: boolean;
        /** Drag to rotate */
        dragRotate?: boolean;
        /** Double click to zoom */
        doubleClickZoom?: boolean;
        /** Pinch to zoom / rotate */
        touchZoomRotate?: boolean;

        /**
         * Called when the map is hovered over.
         * @callback
         * @param {Object} event - The mouse event.
         * @param {[number, number]} lngLat - The coordinates of the pointer
         * @param {Array} features - The features under the pointer, using Mapbox's
         * queryRenderedFeatures API:
         * https://www.mapbox.com/mapbox-gl-js/api/#Map#queryRenderedFeatures
         * To make a layer interactive, set the `interactive` property in the
         * layer style to `true`. See Mapbox's style spec
         * https://www.mapbox.com/mapbox-gl-style-spec/#layer-interactive
         */
        onHover?: (event: any, lngLat: number[], features: any) => void;

        /**
         * Called when the map is clicked.
         * @callback
         * @param {Object} event - The mouse event.
         * @param {[number, number]} lngLat - The coordinates of the pointer
         * @param {Array} features - The features under the pointer, using Mapbox's
         * queryRenderedFeatures API:
         * https://www.mapbox.com/mapbox-gl-js/api/#Map#queryRenderedFeatures
         * To make a layer interactive, set the `interactive` property in the
         * layer style to `true`. See Mapbox's style spec
         * https://www.mapbox.com/mapbox-gl-style-spec/#layer-interactive
         */
        onClick?: (event: any, lngLat: number[], features: any) => void;

        /** Radius to detect features around a clicked point. Defaults to 0. */
        clickRadius?: number;

        /** Accessor that returns a cursor style to show interactive state */
        getCursor?: () => any;

        /** Advanced features */
        /**
         * Contraints for displaying the map. If not met, then the map is hidden.
         * Experimental! May be changed in minor version updates.
         */
        visibilityConstraints?: {
            minZoom: number;
            maxZoom: number;
            minPitch: number;
            maxPitch: number;
        };

        /**
         * A map control instance to replace the default map controls
         * The object must expose one property: `events` as an array of subscribed
         * event names; and two methods: `setState(state)` and `handle(event)`
         */
        mapControls?: {
            events: string[];
            handleEvent: (e: any) => void;
        };
    }

    export class InteractiveMap extends React.Component<IInteractiveMapProps, {}> {
        public _map: mapboxgl.Map;

        /**
         * Returns the Mapbox instance if initialized. The Map instance will have full access to MapboxGL's API.
        */
        getMap(): mapboxgl.Map;
    }
}

declare module "react-map-gl" {
    const MapGL = ReactMapGL.InteractiveMap;
    // export = MapGL;
    export default MapGL;
}

namespace ReactMapGL {
    import * as Immutable from "immutable";

    type ICompositeOperation =
        | "source-over"
        | "source-in"
        | "source-out"
        | "source-atop"
        | "destination-over"
        | "destination-in"
        | "destination-out"
        | "destination-atop"
        | "lighter"
        | "copy"
        | "xor"
        | "multiply"
        | "screen"
        | "overlay"
        | "darken"
        | "lighten"
        | "color-dodge"
        | "color-burn"
        | "hard-light"
        | "soft-light"
        | "difference"
        | "exclusion"
        | "hue"
        | "saturation"
        | "color"
        | "luminosity";

    interface IScatterplotOverlayProps {
        width: number;
        height: number;
        latitude: number;
        longitude: number;
        zoom: number;
        isDragging: boolean;
        locations: Immutable.List<number[]>;
        lngLatAccessor?: (o: any) => number[];
        renderWhileDragging?: boolean;
        globalOpacity?: number;
        dotRadius?: number;
        dotFill?: string;
        compositeOperation?: ICompositeOperation;
    }

    export class ScatterplotOverlay extends React.Component<IScatterplotOverlayProps, {}> {}
}

declare module "react-map-gl/dist/overlays/scatterplot.react" {
    const ScatterplotOverlay = ReactMapGL.ScatterplotOverlay;
    export default ScatterplotOverlay;
}

[balthazar]

The typings should only be represented by a single file and referenced using the types package field, we shouldn't need a separate example folder as users have different configurations / expectations and it's not really in scope.

[fnberta]

Yes, but @rimig mentioned an important point, we might want to put them on DefinitelyTyped instead of including them directly in the package. The reason being that the types will depend on other type definitions (specifically react, geojson and mapbox-gl). f you don't want @types/... packages in your devDependencies, DefinitelyTyped is probably the better options. Thoughts?

I hope to have a definition file ready by the end of the week.

[rimig]

@fnberta did you make any progress here?

[rimig]

Went ahead and did it, this doesn't provide full coverage but it's a start:
https://github.com/DefinitelyTyped/DefinitelyTyped/pull/24125

[rimig]

Closing this since it's done, you can grab typings with:
yarn add @types/react-map-gl

[ibgreen]

Nice! Could be added to documentation, maybe installation page?

[fnberta]

@rimig Sorry for the long silence, got caught up in work. Awesome job with the typings, thanks a lot! I made a PR on DefinitelyTyped with some additions/changes, let me know what you think! See https://github.com/DefinitelyTyped/DefinitelyTyped/pull/25007