# API reference

Every export of every entry of the @maplacejs/maplace package, with its error codes and the capabilities of each map provider.

Every export of every entry, with where it is explained, then the error codes and the capabilities. One package, one version for all entries; the package is ES modules only.

## `@maplacejs/maplace`

The store, the list view, the GeoJSON helper, the adapter contract and the types. Side-effect-free.

| Export | Kind | Explained in |
|---|---|---|
| `createMaplace` | function | [Creating a store](/store/#creating-a-store) |
| `MaplaceOptions` | type | [Store options](/store/#options) |
| `HeatmapOptions` | type | [Heatmaps](/store/#heatmaps) |
| `Maplace` | type | [Methods](/store/#methods) |
| `Snapshot`, `LoadState` | types | [Snapshot](/store/#snapshot) |
| `FilterRequest`, `LocationFilter` | types | [`setFilter`](/store/#methods) |
| `LocationGroup` | type | [Subgroups](/store/#subgroups) |
| `PopupOptions` | type | [Popup options](/store/#popup-options) |
| `View`, `Viewport`, `Bounds`, `FitOptions`, `SelectOptions` | types | [The first view](/store/#the-first-view), [methods](/store/#methods) |
| `MaplaceEvents`, `MaplaceEventName`, `Listener`, `ListenOptions`, `Unsubscribe` | types | [Events](/store/#events) |
| `Route`, `RouteResult`, `RouteLeg`, `RouteStep`, `TravelMode` | types | [Routes](/store/#routes) |
| `RouteComputer`, `RouteRequest`, `RouteRequestStop`, `RouteAnswer` | types | [Routes on MapLibre](/maplibre/#routes) |
| `createListView` | function | [List view options](/store/#list-view-options) |
| `distanceTo` | function | [Distances](/store/#distances) |
| `createMyLocationControl`, `MyLocationControl`, `MyLocationOptions` | function, types | [The "My location" control](/store/#the-my-location-control) |
| `ListViewOptions`, `ListView`, `ListEntry` | types | [List view options](/store/#list-view-options) |
| `listedLocations` | function | [Listed locations](/store/#listed-locations) |
| `locationsFromGeoJSON` | function | [From GeoJSON](/locations/#from-geojson) |
| `pointAlong` | function | [A point along a line](/locations/#a-point-along-a-line) |
| `GeoJSONFeatureCollection`, `GeoJSONFeature` | types | [From GeoJSON](/locations/#from-geojson) |
| `Location`, `MarkerLocation`, `CircleLocation`, `PolylineLocation`, `PolygonLocation`, `MultiPolygonLocation` | types | [Locations](/locations/) |
| `LatLng`, `Geometry`, `MarkerGeometry`, `CircleGeometry`, `PolylineGeometry`, `PolygonGeometry`, `MultiPolygonGeometry`, `PolygonRings` | types | [Locations](/locations/#markers); a geometry is what a drag or edit changes |
| `Content` | type | [Content](/locations/#content) |
| `Icon`, `LocationState` | types | [Icons](/locations/#icons) |
| `LineStyle`, `ShapeStyle`, `StrokeDash` | types | [Styles](/locations/#styles) |
| `MaplaceError`, `MaplaceErrorDetails` | class, type | [Errors](#errors) |
| `ErrorCode`, `MisuseCode`, `RuntimeCode` | types | [Misuse codes](#misuse-codes), [runtime failures](#runtime-failures) |
| `Capability` | type | [Capabilities](#capabilities) |
| `ControlPosition` | type | A corner of the map: [`<MapControl>`](/react/#mapcontrol), [`<LocationList>`](/react/#locationlist)'s `position` |
| `Adapter`, `AdapterHost`, `MountContext`, `LocationDiff`, `PresentationState`, `Drawable`, `ResolvedPopupOptions`, `ResolvedView` | types | The adapter contract, for a new provider: [RFC §3 Shape](https://github.com/danielemoraschi/maplace.js/blob/5dd17eac33e258107f91c7a4d4d05bc2673e17bd/docs/rfc-1.0.md#shape) |

## `@maplacejs/maplace/google`

The Google Maps adapter: the only entry that knows `google.maps`.

| Export | Kind | Explained in |
|---|---|---|
| `createGoogleAdapter` | function | [Google adapter](/google/) |
| `GoogleAdapterOptions` | type | [Options](/google/#options) |
| `createGoogleMap` | function | [`createGoogleMap`](/google/#creategooglemap) |
| `GoogleMapOptions`, `GoogleMapList`, `GoogleMapMyLocation` | types | [`createGoogleMap`](/google/#creategooglemap) |

## `@maplacejs/maplace/maplibre`

The MapLibre GL JS adapter, on OpenFreeMap's tiles unless a style says otherwise: the only entry that knows `maplibre-gl`, which the page installs, with its stylesheet.

| Export | Kind | Explained in |
|---|---|---|
| `createMapLibreAdapter` | function | [MapLibre adapter](/maplibre/) |
| `MapLibreAdapterOptions`, `MapLibreGlobe` | types | [Options](/maplibre/#options) |
| `createMapLibreMap` | function | [`createMapLibreMap`](/maplibre/#createmaplibremap) |
| `MapLibreMapOptions`, `MapLibreMapList`, `MapLibreMapMyLocation` | types | [`createMapLibreMap`](/maplibre/#createmaplibremap) |

## `@maplacejs/maplace/element`

`<maplace-map>` and `<maplace-location>`, defined on import, with no provider registered.

| Export | Kind | Explained in |
|---|---|---|
| `defineProvider`, `ProviderFactory` | function, type | [Providers](/element/#providers) |
| `defineListView`, `ListViewFactory`, `ListViewSetup`, `ElementListOptions` | function, types | [List views](/element/#list-views) |
| `ListPosition` | type | [Map attributes](/element/#map-attributes): `list-position` |
| `MaplaceMapElement` | type | [Properties and methods](/element/#properties-and-methods) |
| `MaplaceLocationElement` | type | [Location attributes](/element/#location-attributes) |
| `MaplaceElementEventMap` | type | [Events](/element/#events) |

## `@maplacejs/maplace/element/google`

The element with the Google provider registered; the Google CDN scripts are this entry bundled.

| Export | Kind | Explained in |
|---|---|---|
| `MaplaceMapElement` | type | [Properties and methods](/element/#properties-and-methods), [provider attributes](/google/#provider-attributes) |

## `@maplacejs/maplace/element/maplibre`

The element with the MapLibre provider registered; the MapLibre CDN script is this entry bundled, with maplibre-gl.

| Export | Kind | Explained in |
|---|---|---|
| `MaplaceMapElement` | type | [Properties and methods](/element/#properties-and-methods), [provider attributes](/maplibre/#provider-attributes) |

## The CDN scripts' `Maplace`

Each CDN script also sets one global, `Maplace`: the exports of `@maplacejs/maplace`, `@maplacejs/maplace/element` and its provider's entry above, so a page's own script calls `Maplace.createGoogleMap(...)` where an npm page imports `createGoogleMap`. The MapLibre script adds `Maplace.maplibre`, the maplibre-gl it bundles. It holds functions, no state: the store a page makes is its own ([with a script of your own](/setup/#with-a-script-of-your-own)).

## `@maplacejs/maplace/react`

The React binding, a client boundary (`"use client"`).

| Export | Kind | Explained in |
|---|---|---|
| `MaplaceProvider`, `MaplaceProviderProps`, `MaplaceControlledProps` | component, types | [`<MaplaceProvider>`](/react/#maplaceprovider) |
| `MaplaceEventProps` | type | [Event props](/react/#event-props) |
| `MaplaceMap`, `MaplaceMapProps`, `PopupContentRender`, `MarkerIconRender` | component, types | [`<MaplaceMap>`](/react/#maplacemap) |
| `LocationList`, `LocationListProps` | component, type | [`<LocationList>`](/react/#locationlist) |
| `MapControl`, `MapControlProps` | component, type | [`<MapControl>`](/react/#mapcontrol) |
| `MyLocation`, `MyLocationProps` | component, type | [`<MyLocation>`](/react/#mylocation) |
| `useMaplace` | hook | [`useMaplace()`](/react/#usemaplace) |

## `@maplacejs/maplace/testing`

The conformance suite, for an adapter of your own; it needs `vitest` (an optional peer) in browser mode, and no page loads it.

| Export | Kind | Explained in |
|---|---|---|
| `describeConformance`, `ConformanceSubject`, `ConformanceGroup` | function, types | [Proving an adapter](/store/#proving-an-adapter) |
| `MapProbe`, `LocationOnMap`, `ShownPopup` | types | [Proving an adapter](/store/#proving-an-adapter) |
| `frontFirst`, `StackedLocation` | function, type | [Proving an adapter](/store/#proving-an-adapter) |
| `SELECTED_LOOK`, `SELECTED_LINE_LOOK`, `HOVERED_LOOK`, `ORIGIN_DOT_CLASS` | constants | [Proving an adapter](/store/#proving-an-adapter) |

## Errors

Misuse throws a `MaplaceError` from the call that caused it, with a `code` and, where they apply, the `locationId` and the `field`. In the element, where no caller can catch a throw, misuse is the element's error state and a `maplace-error` event instead ([misuse](/element/#misuse)); in React it throws from render or a layout effect, to the nearest error boundary. Runtime failures are never thrown: they are `error` events, with the same `MaplaceError`.

## Misuse codes

| Code | When |
|---|---|
| `invalid-input` | Bad data or arguments: a wrong or unknown field, a value out of range, a shape with too few points, a hidden location selected or hovered; the full list is in [RFC §3 Errors](https://github.com/danielemoraschi/maplace.js/blob/5dd17eac33e258107f91c7a4d4d05bc2673e17bd/docs/rfc-1.0.md#errors) |
| `duplicate-id` | Two locations with one id |
| `unknown-id` | An id not in the store: `select`, `hover`, `selectedId`, a route stop |
| `unsupported-capability` | A feature the adapter lacks |
| `missing-sanitizer` | `html` without `sanitize` |
| `already-attached` | A store attached twice, or an adapter reused |
| `destroyed` | A call after `destroy` that changes state or adds a listener |

Before `attach` the store skips capability checks; `attach` checks the current state against the adapter, and afterwards each call checks before changing anything.

## Runtime failures

| Code | When |
|---|---|
| `provider-load-failed` | The provider, or a part it loads (maplibre-gl, its worker, a style, the clusterer), failed to load; on Google also your own map made without a map ID |
| `provider-auth-failed` | The provider refused the key: Google's, or a style's server (HTTP 401 or 403) |
| `route-failed` | A route couldn't be computed |

For the first two, `loadState` becomes `error` and `whenReady()` rejects; one that comes after `ready` moves `loadState` from `ready` to `error`. A map Maplace.js creates also says so on the map when it can't be used: a [panel](/styling/#classes) in its container, none on your own map. An `icon`, `content` or `sanitize` function of yours that fails while the map draws is an `invalid-input` error event naming the location and the field: the map stays ready.

## Capabilities

A capability is a feature an adapter may or may not support; using one the adapter lacks is `unsupported-capability`. Google has all six; MapLibre has `route` only with your own routing, as it has none ([routes](/maplibre/#routes)).

| Capability | What it allows |
|---|---|
| `route` | `setRoute`, the element's `route` and React's `route` prop |
| `cluster` | The `cluster` option |
| `circle` | Circle locations |
| `edit` | `editable` locations |
| `multipolygon` | Multipolygon locations (1.2); an adapter written for 1.0 lacks it, so the store refuses them there |
| `heatmap` | The `heatmap` option (1.2), drawn by maplace on both providers; an adapter written for 1.0 lacks it |

## Rules

- camelCase throughout; verbs for methods, nouns for types, one word per concept, and no two ways to do the same thing.
- At most two positional arguments, then an options object; never a boolean flag: `select(id, { pan: false })`, not `select(id, false)`.
- Absence is `undefined`, never `null`.
- Views know only the store, adapters know only their host, and only the element (or your code) wires them together.

The full rules are in [RFC §3](https://github.com/danielemoraschi/maplace.js/blob/5dd17eac33e258107f91c7a4d4d05bc2673e17bd/docs/rfc-1.0.md#rules-the-api-follows).
