JavaScript API

Integration with React

Note

The JS API supports integration with React JS only.

At the moment, there is no support for React Native.

Quick start

Warning

Supported React version: at least 16

Connecting via top-level-await

<!DOCTYPE html>
<html>
  <head>
    <!-- Substitute the value of the real key instead of YOUR_API_KEY -->
    <script src="https://js.api.mappable.world/v3/?apikey=YOUR_API_KEY&lang=en_US"></script>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

import ReactDOM from 'react-dom/client';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
root.render(<App />);

import {MMap, MMapDefaultSchemeLayer, MMapDefaultFeaturesLayer, MMapMarker, reactify} from './lib/mappable';
import type {MMapLocationRequest} from 'mappable';

const LOCATION: MMapLocationRequest = {
  center: [25.229762, 55.289311],
  zoom: 9
};

export default function App() {
  return (
    <div style={{width: '600px', height: '400px'}}>
      <MMap location={reactify.useDefault(LOCATION)}>
        <MMapDefaultSchemeLayer />
        <MMapDefaultFeaturesLayer />

        <MMapMarker coordinates={reactify.useDefault([25.229762, 55.289311])} draggable={true}>
          <section>
            <h1>You can drag this header</h1>
          </section>
        </MMapMarker>
      </MMap>
    </div>
  );
}

import React from 'react';
import ReactDom from 'react-dom';

const [mappableReact] = await Promise.all([mappable.import('@mappable-world/mappable-reactify'), mappable.ready]);

export const reactify = mappableReact.reactify.bindTo(React, ReactDom);
export const {MMap, MMapDefaultSchemeLayer, MMapDefaultFeaturesLayer, MMapMarker} = reactify.module(mappable);

{
  "compilerOptions": {
    "target": "es2017",
    "lib": ["dom", "dom.iterable", "esnext"],
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "jsx": "react-jsx",
    "typeRoots": ["./node_modules/@types", "./node_modules/@mappable-world/mappable-types"],
    "paths": {
      "mappable": ["./node_modules/@mappable-world/mappable-types"]
    }
  }
}

{
  "devDependencies": {
    "@types/react": "^18.3.3",
    "@types/react-dom": "^18.3.0",
    "@mappable-world/mappable-types": "^0.0.10",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-scripts": "5.0.1",
    "typescript": "^4.9.5"
  },
  "scripts": {
    "start": "react-scripts start"
  }
}

Install the dependencies and start the local server:

npm install
npm start

Open application

Specificities

  1. In package.json adding a dev-dependency on the package @mappable-world/mappable-types.

    It is recommended to install the latest version:

    npm i --save-dev @mappable-world/mappable-types@latest

  2. In tsconfig.json we set compilerOptions.typeRoots with a list of paths to file types. Adding the path to the package @mappable-world/mappable-types there, so that the namespace mappable with types appears in the global scope.

    Note

    The namespace mappable contains all the class types that the JS API provides, but they are not available in the runtime until the resolving mappable.ready.

  3. In tsconfig.json we set compilerOptions.paths, in which we inform the ts compiler that when importing the package mappable, its content should be searched for in the specified path. Thanks to this, you can import types in project files as if they are not in the @mappable-world/mappable-types, but in the mappable package:

    import type {MMapLocationRequest} from 'mappable';

    All types must be imported from the root.

    The internal structure is not guaranteed and may change over time.

  4. In tsconfig.json, for top-level-await to work correctly, the parameter compilerOptions.module must be set to one of the following values: es2022, esnext, system or preserve. Also the compilerOptions.target parameter must be es2017 or higher.

  5. For each object in the JS API, there is a React analog. To use the React API version, connect the @mappable-world/mappable-reactify module. In the lib/mappable.ts file, we wait for the JS API and reactify module to be fully loaded, after which we export the necessary map components for use in other parts of the project:

    import React from 'react';
import ReactDom from 'react-dom';

const [mappableReact] = await Promise.all([mappable.import('@mappable-world/mappable-reactify'), mappable.ready]);

export const reactify = mappableReact.reactify.bindTo(React, ReactDom);
export const {MMap, MMapDefaultSchemeLayer, MMapDefaultFeaturesLayer} = reactify.module(mappable);

    Note

    The @mappable-world/mappable-reactify module provides a set of methods for accessing React to both individual objects and modules/packages in general. The hierarchy of objects and initialization parameters is the same.

  6. Using top-level-await in lib/mappable.ts guarantees the execution of mappable.ready and mappable.import('@mappable-world/mappable-reactify') before importing map components, which allows you to synchronously use any JS API objects as React components:

    <MMap location={reactify.useDefault(LOCATION)}>
  <MMapDefaultSchemeLayer />
  <MMapDefaultFeaturesLayer />
  ...
</MMap>

reactify.useDefault

MMap and all other components are uncontrollable by design. Components use imperative API (e.g. MMapZoomControl calls MMap.update({location})). This may cause desynchronization with props and state in React (e.g. location in MMap or coordinates on MMapMarker with enabled drag).

Use reactify.useDefault(value) to set prop once and don't update it in rerenders.
E.g. <MMap location={reactify.useDefault({center, zoom})}/> will behave like <input defaultValue={''}/>.

To precisely control prop update pass array of dependencies as a second argument to reactify.useDefault(value, deps) like in React hooks (e.g. useCallback, useMemo, useEffect).
Prop will be updated if dependencies array differs from the last one.

For object parameters value itself can be used as a dependency, if value references differ. E.g. const [location, setLocation] = useState(...), reactify.useDefault(location, [location]), setLocation({...}).

reactify.useDefault works with any prop of any component returned from reactify.

Warning

reactify.useDefault returns opaque object with no public API and MUST be used only directly in props.

Custom implementations of objects mappable.MMapEntity for React

Use the overrideKey key to define a custom implementation of mappable.MMapEntity objects for reactify:

type MMapSomeClassProps = {
  id: string;
};
export class MMapSomeClass extends mappable.MMapComplexEntity<MMapSomeClassProps> {
  static [mappableReactify.reactify.overrideKey] = MMapSomeClassReactifyOverride;
  //...
}

and define a method for determining user implementation:

export const MMapSomeClassReactifyOverride = (
  MMapSomeClassI, // MMapSomeClass base class
  {reactify, React}
) => {
  const MMapSomeClassReactified = reactify.entity(MMapSomeClassI); // Standard reactify method
    const MMapSomeClassR = React.forwardRef((props, ref) => {
      return (<>
        <MMapSomeClassReactified {...props} ref={ref} ... />
      </>);
    })
  return MMapSomeClassR;
}

and add the resulting component to the application:

import {MMapSomeClass} from './some-class';
import React from 'react';
import ReactDOM from 'react-dom';
// ...
const mappableReactify = await mappable.import('@mappable-world/mappable-reactify');
const reactify = mappableReactify.reactify.bindTo(React, ReactDOM);
const MMapSomeClassR = reactify.entity(MMapSomeClass);

function App() {
  return <MMapSomeClassR id="some_id" />;
}
In this article: