@spec bbox(term()) :: Rover.Geo.bbox() | nil

The bounding box of anything fit_to/4 accepts, as {south, west, north, east}.

Markers, shapes, plain coordinates, a mixed list, or a box passed through unchanged. nil when there is nothing to enclose.

Examples

iex> Rover.bbox([%{id: 1, lat: 45.0, lon: 4.0}, %{id: 2, lat: 46.0, lon: 5.0}])
{45.0, 4.0, 46.0, 5.0}

iex> Rover.bbox({45.0, 4.0, 46.0, 5.0})
{45.0, 4.0, 46.0, 5.0}

iex> Rover.bbox(%{"south" => 45.0, "west" => 4.0, "north" => 46.0, "east" => 5.0})
{45.0, 4.0, 46.0, 5.0}

iex> Rover.bbox([])
nil

@spec fit_to(Phoenix.LiveView.Socket.t(), String.t(), term(), keyword()) ::
  Phoenix.LiveView.Socket.t()

Frames a map's view around some content, without making the view part of your state.

The counterpart to fly_to/4 for "show me these": pass markers, shapes, coordinates, or a {south, west, north, east} bounding box, and the client fits the view to it — using the viewport size, which only the client knows.

{:noreply, Rover.fit_to(socket, "fleet", vehicles_on_shift)}

Like fly_to/4, this counts as the map's initial framing: content arriving afterwards will not pull the view back off what you framed.

Options

• :padding — pixels kept clear around the content. Defaults to 48.
• :max_zoom — how far in the fit may go. Defaults to 16, which stops a single point from filling the screen.
• :duration — animation length in milliseconds. Defaults to 500.

Returns the socket untouched when there is nothing to frame, so fit_to(socket, "fleet", []) is a no-op rather than an error.

@spec fly_to(Phoenix.LiveView.Socket.t(), String.t(), Rover.Geo.coordish(), keyword()) ::
  Phoenix.LiveView.Socket.t()

Moves a map's view, without making the view part of your state.

center and zoom are attributes, which is right when the view is a property of what you are rendering. It is the wrong tool for "the user clicked a row, take me there": passing center costs you the automatic framing — fit falls back to false and the centre stops being derived — so you trade the default behaviour for one gesture, and you have to keep the view in assigns from then on.

This is a one-shot command instead. Nothing is assigned, no attribute changes, and the map keeps its declarative framing for everything else.

It does count as the map's initial framing, though: a map with no center is framed around its content once, and a flight is a decision about the view, so content arriving afterwards will not pull it back. fit={true} still refits on every change.

def handle_event("select_client", %{"id" => id}, socket) do
  client = Enum.find(socket.assigns.clients, &(&1.id == id))

  {:noreply, Rover.fly_to(socket, "clients", {client.lat, client.lon}, zoom: 15)}
end

Options

• :zoom — where to end up. Omit to keep the current zoom.
• :duration — animation length in milliseconds. Defaults to 500. 0 jumps.

The first argument to identify is the map's DOM id, because a LiveView can hold several maps and an event reaches all of them.

@spec start_drawing(Phoenix.LiveView.Socket.t(), String.t(), keyword()) ::
  Phoenix.LiveView.Socket.t()

Arms the map for drawing, so the user can put a new shape on it.

:editable lets a user reshape a geometry that already exists. This is the other half: there is nothing to attach a per-item flag to yet, so drawing is a one-shot command like fly_to/4 rather than an attribute — a mode the server turns on for a gesture and turns off again.

def handle_event("draw_parcel", _params, socket) do
  {:noreply, Rover.start_drawing(socket, "parcels", type: :polygon)}
end

The finished geometry arrives on on_draw_end, with no :id — the shape does not exist yet, and identity is yours to assign:

def handle_event("drew", %{"geometry" => geometry}, socket) do
  parcel = %{id: System.unique_integer([:positive]), geometry: geometry}

  {:noreply,
   socket
   |> assign(parcels: socket.assigns.parcels ++ [parcel])
   |> Rover.stop_drawing("parcels")}
end

The mode stays armed until stop_drawing/2, so a user asked to trace four parcels traces four without touching the toolbar again. Escape abandons the sketch in progress and leaves the mode armed, the way it does in every drawing tool.

While it is armed the map claims every click — on_marker_click, on_shape_click, on_cluster_click and on_map_click all stop firing, and popups stop opening. A click that places a vertex is not a click on whatever sits under it. Because the mode persists, leaving it armed leaves the map's other click behaviour off with it.

Options

• :type — :polygon (the default), :line or :point.

There is no :circle. OpenLayers can draw one, GeoJSON has no way to represent one, and a shape that cannot round-trip through Rover.Shape would be a geometry the server could never store or send back.

A map rendered with interactive={false} refuses to arm: it is a picture, and drawing is the largest interaction there is.

@spec stop_drawing(Phoenix.LiveView.Socket.t(), String.t()) ::
  Phoenix.LiveView.Socket.t()

Disarms a map armed by start_drawing/3, and discards any unfinished sketch.

Calling it on a map that is not drawing does nothing.