@getcircuit/web-map

@getcircuit/web-map

Circuit Schema | Svelte Documentation | Google Maps Documentation

• Usage
• API
• Marker
  • Marker color definition
  • Marker size definition
  • Marker content definition

Usage

General

The general way to use this component is to instantiate it as you would with any other Svelte component.

import CircuitMap from '@getcircuit/web-map'
import ReactDOM from 'react-dom/client'
import React from 'react'
import { DriverAvatar } from '@getcircuit/components'
import { AttemptedLocationCard } from '../somewhere'

const mapInstance = new CircuitMap({
  target: document.querySelector('#map'),
  props: {
    apiKey: '...',
    mapOptions: {
      center: { lat: 51.509865, lng: -0.118092 },
      zoom: 15,
    },
    react: {
      React,
      ReactDOM,
      components: {
        DriverAvatar,
        AttemptedLocationCard,
      },
    },
  },
})

API

apiKey

Google Maps API key.

mapOptions

Google maps options object.

Methods

setIntl(newIntl: IntlStore): void

Updates the map's Intl bag. An Intl bag is an object composed of the following properties:

type IntlBag {
  /** Current locale */
  locale: string
  /** Method that returns a localized message given a message id */
  formatMessage: (messageId: string, values?: Record<string, any>) => string
  /** Method that formats an epoch timestamp given the current locale */
  formatEpoch: (epoch: EpochTimestamp) => string
}

setMapOptions(options: google.maps.MapOptions): void

Updates map's Google Map options.

setCenter(center: google.maps.LatLngLiteral | google.maps.LatLng): void

Changes the center of the map to the specified point.

fitCoordinates(coords?: google.maps.LatLngLiteral[]): void

Moves the map camera to fit all the passed coordinates.

setPlan(newPlan?: PlanBundle): void

Updates the current plan that is being displayed on the map. Set to undefined to remove the current plan.

focusRoute(routeId: string): void

Focuses the given route on the map.

focusStop(stopId: string): void

Focuses the given stop on the map.

resetFocus(): void

Resets the map focus state.

hoverRoute(routeId: string): void

Hovers the given route on the map.

hoverStop(stopId: string): void

Hovers the given stop on the map.

resetHover(): void

Resets the map hover state.

openAttemptedLocationCard(): void

Opens the Attempted Location Card component for the current focused stop.

closeAttemptedLocationCard(): void

Closes the Attempted Location Card component.

Map Camera

Loom

The map camera should behave as stated below:

• Use CubicInOut for 600ms when there’s no change to zoom levels, regardless of the distance between points A and B.
• If there’s a zoom level change, skip the animation (0 duration).
• When focusing a stop:
  • Minimum zoom level is 16, maximum zoom level is not defined.
  • Maximum zoom level is 16 if the stop being focused has an attempted location more than 100 meters away from the original stop location and the user is on a zoom level lower than 16. If user is on a greater zoom level, try to fit the stop and attempted markers with the current zoom level.
• The camera supports padding in px
  • The camera center is moved according to the padded area.
  • The default padding of the camera is 50px in all directions.
• The camera should keep track of manual movements made by the user.
  • If the user has not moved the camera manually:
    • Unfocusing a route stop moves the camera to the whole stop's route.
    • Unfocusing a unassigned stop moves moves the camera to the whole plan.
  • If the user has moved the camera manually:
    • Unfocusing a stop should move the camera back to the user position, but the route should be focused.
    • Unfocusing a route should move the camera back to the user position and nothing should be on focus..

Polyline

TBD

Marker

Marker types

There are 2 different types of markers:

• Detailed markers
• Minimal markers

Detailed markers

Detailed markers can show additional information about the stop like their number if used for an optimized stop as well as different state-dependent symbols. They don't have to show anything, f.e. when used for unoptimized stops.

Detailed marker color definition

The color preset of a detailed marker depends on its stop state with the following precedence:

• If stop was deleted, use the neutral color preset.
• If stop was skipped, use the error color preset.
• (todo) If stop has an issue, use the error color preset.
• If stop was added after an optimization, use the neutral color preset.
• If stop was edited after an optimization, use the route's color preset.
• If stop is part of a route, use the route's color preset.
• If stop is not part of a route, use the default color preset.

Apart from the color preset, the colors that will be used depend on the marker variant. The available variants are: primary, secondary, focused.

• The marker is focused if the stop is focused.
• The marker is primary if any of the following are true:
  • the stop's route is hovered.
  • the plan is finished and no other route is focused.
  • the stop is not done, and no other route is focused, and no other stop is focused.
• The marker is secondary if any of the following are true:
  • another route is focused.
  • another stop is focused.
  • the stop is done.
  • the stop is not done, but the route is finished and the stop is of type end.

Detailed marker size definition

A detailed marker can have one of four different widths: 1 to 4, used depending on how much content needs to be shown inside the marker.

Width 1:

• When there's just an icon, no digit (for example for the "excluded from route" pin).
• When there are 1 or 2 digits, no icon (stops 1-99, with no other status).

Width 2:

• When there are 3 digits and no icon (stops 99-999, with no other status).
• When there's 1 digit plus an icon.

Width 3:

• When there are 2 digits plus an icon.

Width 4:

• When there are 3 digits plus an icon.

Detailed marker content definition

• The content of a detailed marker can be:
  • symbol only
  • text only
  • text and symbol
• A marker only contains text if stop is part of a route and is not a terminal location.
• Terminal locations markers contain only a symbol.
• The appropriate symbol is rendered following these rules:
  • (todo) If stop was deleted, use deleted symbol.
  • If stop was skipped, use unreachable symbol.
  • If stop was added after an optimization and it's unassigned, for detailed markers, use unoptimized symbol.
  • If stop is the start location, use start symbol.
  • If stop is the end location, use end symbol.
  • For detailed markers:
    • If stop is assigned (part of a route) and optimized
      • If stop delivery was attempted:
        • If unsuccessful, use failure symbol.
        • If successful and stop is focused, use success symbol.
        • If successful and stop is not focused, don't use a symbol.
      • If stop delivery was not attempted:
        • If stop was changed/edited, use edited symbol.
        • If stop has optimization order set as first use orderFirst symbol.
        • If stop has optimization order set as last use orderLast symbol.
        • If stop is pickup, use pickup symbol.
    • If stop is unassigned (not part of a route) or not optimized:
      • If stop has optimization order set as first use orderFirst symbol.
      • If stop has optimization order set as last use orderLast symbol.
      • If stop is pickup, use pickup symbol.
      • Otherwise, use unoptimized symbol.

Any symbol listed above can be replaced by one of higher precedence.

For stops that are not a terminal location, the priority order of its symbol is:

Deleted > Unreachable > Added > Edited > Failure > Success > Issue > Pickup > ASAP

Minimal markers

Minimal markers are used to reduce the visual overlap of markers on dense routes, allowing the user to get a better view of the planned routes.

Compared to detailed markers, they are smaller and don't show any text. Also, only the start / end / skipped symbols are shown where applicable.

Minimal marker color definition

The color preset of a minimal marker depends on its stop state with the following precedence:

• If stop was skipped, use the error color preset.
• If stop is part of a route, use the route's color preset.
• If stop is not part of a route, use the default color preset.

Apart from the color preset, the colors that will be used depend on the marker variant. The available variants are: focused, primary, secondary, tertiary and unassigned.

• The marker is focused if the stop is focused.
• The marker is unassigned if the stop isn't assigned to a route and it's not focused.
• The marker is primary if any of the following are true:
  • the stop's route is hovered.
  • the plan is finished and no other route is focused.
  • the stop is not done, and no other route is focused, and no other stop is focused.
• The marker is secondary if any of the following are true:
  • another route is focused.
  • another stop is focused.
  • the stop is done.
  • the stop is not done, but the route is finished and the stop is of type end.
• The marker is tertiary if the batch-edit selection-mode is active and the stop is not done.

Minimal marker size definition

A minimal marker can have one of two different widths: 1 and 2.

Width 1:

• When there's no content to display.

Width 2:

• When we want to show an symbol, f.e. for start- & end-location markers or skipped stops.

Minimal marker content definition

• The content of a minimal marker can only be:
  • symbol only
• A minimal marker never contains any text.
• Terminal or skipped locations markers contain only a symbol.
• The appropriate symbol is rendered following these rules:
  • If stop was skipped, use unreachable symbol.
  • If stop is the start location, use start symbol.
  • If stop is the end location, use end symbol.