HoloMap.API (HoloMap v0.1.0)

Imperative commands for things that are not state.

Most of a map belongs in component props: which layers exist, how they are painted, what the camera is looking at. Some of it does not. "Fly to the result the user just picked" is an event, not a value. Re-rendering the same centre twice should not re-animate, and animating is the whole point.

These functions are for that second category. Call them from an action:

def action(:show_parcel, params, component) do
  HoloMap.API.fly_to("explorer", center: {params.lng, params.lat}, zoom: 17)
  put_state(component, :selected, params.id)
end

The first argument is always the map's cid, the same string given to HoloMap.Map.

Actions only

These calls compile to no-ops on the server. They work in action/3 and in functions an action reaches; they do nothing in init/3 or command/3.

Choosing between this and props

Situation	Use
The camera reflects application state	`HoloMap.Map`'s `center`/`zoom` props
The camera should animate in response to an event	`fly_to/2`, `ease_to/2`
A layer's paint reflects state	`HoloMap.Layer.*`'s `paint` prop
A one-off highlight that should not survive a re-render	`set_paint_property/4`

Anything set imperatively is overwritten the next time the declarative specification for that object changes. The reconciler treats the rendered props as the source of truth.

Summary

Functions

ease_to(cid, opts)

Animates the camera along a straight path, without the zoom-out arc.

fit_bounds(cid, bounds, opts \\ [])

Fits the camera to a bounding box.

fly_to(cid, opts)

Animates the camera along a curved flight path.

jump_to(cid, opts)

Moves the camera with no animation at all.

remove_feature_state(cid, feature, key \\ nil)

Clears feature state.

resize(cid)

Recomputes the map's size after its container has been resized.

set_feature_state(cid, feature, state)

Attaches feature state, the mechanism behind hover and selection styling.

set_filter(cid, layer_id, filter)

Sets a layer's filter, or clears it when filter is nil.

set_layout_property(cid, layer_id, property, value)

Sets one layout property on a layer.

set_paint_property(cid, layer_id, property, value)

Sets one paint property on a layer.

set_style(cid, style)

Replaces the whole style.

Functions

ease_to(cid, opts)

@spec ease_to(
  String.t(),
  keyword()
) :: :ok

Animates the camera along a straight path, without the zoom-out arc.

Takes the same options as fly_to/2 minus the flight-specific :speed and :curve, which it ignores.

fit_bounds(cid, bounds, opts \\ [])

@spec fit_bounds(String.t(), term(), keyword()) :: :ok

Fits the camera to a bounding box.

bounds accepts any shape HoloMap.Spec.bounds/1 understands: a pair of corners, or a flat [west, south, east, north] list.

HoloMap.API.fit_bounds("explorer", [-71.0, 19.0, -70.0, 20.0], padding: 48)

fly_to(cid, opts)

@spec fly_to(
  String.t(),
  keyword()
) :: :ok

Animates the camera along a curved flight path.

Accepts :center, :zoom, :bearing, :pitch, :duration, :speed, :curve, :offset, :padding, :max_duration, :essential and :animate.

HoloMap.API.fly_to("explorer", center: {-70.66, 19.45}, zoom: 14, duration: 1_200)

jump_to(cid, opts)

@spec jump_to(
  String.t(),
  keyword()
) :: :ok

Moves the camera with no animation at all.

remove_feature_state(cid, feature, key \\ nil)

@spec remove_feature_state(String.t(), map(), String.t() | nil) :: :ok

Clears feature state.

Omit key to clear every state entry on the feature.

resize(cid)

@spec resize(String.t()) :: :ok

Recomputes the map's size after its container has been resized.

Almost never needed. MapLibre observes its own container, so a map whose container changes size follows along by itself and calling this does nothing. That holds for CSS transitions, flex reflows and window resizes alike.

The one case where it is required is a map built with track_resize={false}, which switches that observer off. The canvas then keeps its old size until this is called:

<HoloMap.Map cid="panel" style={@style} width={@width} track_resize={false} />

def action(:panel_resized, _params, component) do
  HoloMap.API.resize("panel")
  component
end

set_feature_state(cid, feature, state)

@spec set_feature_state(String.t(), map(), map()) :: :ok

Attaches feature state, the mechanism behind hover and selection styling.

feature identifies the feature: %{source: "parcels", id: 12}, plus :source_layer for a vector source.

HoloMap.API.set_feature_state("explorer", %{source: "parcels", id: id}, %{hover: true})

set_filter(cid, layer_id, filter)

@spec set_filter(String.t(), String.t(), list() | nil) :: :ok

Sets a layer's filter, or clears it when filter is nil.

HoloMap.API.set_filter("explorer", "parcels-fill", ["==", ["get", "zone"], "R1"])

set_layout_property(cid, layer_id, property, value)

@spec set_layout_property(String.t(), String.t(), atom() | String.t(), term()) :: :ok

Sets one layout property on a layer.

Useful for toggling visibility without removing the layer:

HoloMap.API.set_layout_property("explorer", "parcels-fill", :visibility, "none")

set_paint_property(cid, layer_id, property, value)

@spec set_paint_property(String.t(), String.t(), atom() | String.t(), term()) :: :ok

Sets one paint property on a layer.

property may be given as an atom in Elixir style (:fill_color) or as the specification name ("fill-color").

set_style(cid, style)

@spec set_style(String.t(), String.t() | map()) :: :ok

Replaces the whole style.

Prefer HoloMap.Map's style prop; a style swap discards every source and layer, and the reconciler re-declares the ones it owns on the next styledata event.