@fusion.dev/helix-docs 0.104.1 → 0.106.0

package/content/maps.mdx

@@ -0,0 +1,431 @@
+---
+description: Add interactive maps to your site, styled with your theme and drawn by MapLibre or Leaflet.
+section: Essentials
+title: Maps
+---
+
+# Maps
+
+Helix Maps puts a frame around a map drawn by MapLibre, Leaflet, or a renderer of
+your own. The frame adds a column of controls and a place for the map credit. You
+add places, routes, areas, live positions, and data as elements inside the
+frame, and `@fusion.dev/helix-map` connects the frame to the renderer and styles
+the map with your theme.
+
+## Add a map
+
+Install Helix, the map connector, and MapLibre:
+
+```sh
+bun add @fusion.dev/helix @fusion.dev/helix-map maplibre-gl
+```
+
+Add the map frame, an element for MapLibre to draw in, and your places:
+
+```html
+<helix-map label="Our stores">
+  <div id="map"></div>
+  <helix-map-marker
+    label="Flagship"
+    lat="30.2672"
+    lng="-97.7431"
+  ></helix-map-marker>
+</helix-map>
+```
+
+Create the map with a style from your theme, then connect it to the frame:
+
+```js
+import '@fusion.dev/helix'
+import 'maplibre-gl/dist/maplibre-gl.css'
+import { colorsReady, connectMap } from '@fusion.dev/helix-map'
+import { followTheme, mapLibreDriver, mapLibreStyle } from '@fusion.dev/helix-map/maplibre'
+import maplibregl from 'maplibre-gl'
+
+const frame = document.querySelector('helix-map')
+const style = (colors) => mapLibreStyle(colors)
+const map = new maplibregl.Map({
+  attributionControl: false,
+  container: 'map',
+  style: style(await colorsReady(frame)),
+})
+
+const connection = connectMap(frame, mapLibreDriver(map))
+connection.fit({ animate: false })
+followTheme(map, frame, style)
+```
+
+## What the connector does
+
+`connectMap` links the frame to the renderer:
+
+- The frame's pan, zoom, rotate, and tilt buttons and keys move the map, using
+  your theme's motion settings. The map moves without animation when a user has asked for
+  reduced motion.
+- The renderer's own keyboard handling and zoom buttons are turned off, so the
+  frame's controls are the only ones.
+- The renderer's credit is shown in the frame's footer.
+- `connection.fit()` frames every place on the map.
+- `connection.disconnect()` puts back everything `connectMap` changed.
+
+Use `mapLibreDriver(map)` for MapLibre GL JS 5 and `leafletDriver(map, L)` for
+Leaflet 1.9. Neither renderer is bundled with Helix, so you can use the version
+you already have. Leaflet draws routes, areas, and points only when you pass it
+`L`.
+
+## Style the map with your theme
+
+`mapLibreStyle(colors)` builds a MapLibre style from five colors in your theme:
+
+- Land uses `surface`.
+- Water uses `info`.
+- Parks use `success`.
+- Main roads use `primary`, your brand color.
+- Smaller roads, buildings, borders, and labels use `foreground`.
+
+It also draws landmarks, highway signs, and neighborhood names:
+
+- A landmark is an icon on a disc and its name, in a color for its kind:
+  parks, museums, schools, hotels, hospitals, stations, and stadiums from zoom
+  14, and food and shops from zoom 16. Each color is a fixed hue at your brand
+  color's lightness, so the kinds stay apart in any theme.
+- A highway's number is on its sign, drawn to the Federal Highway
+  Administration's outlines: the red and blue Interstate shield, the white US
+  route shield, the white circle of a state route, and a plain plate for other
+  roads.
+- Neighborhoods are in spaced capitals, quieter than the towns.
+
+The same call builds a light map for a light theme and a dark map for a dark
+theme. Map labels meet a contrast target of 4.5 against the land. Pass
+`contrast` to change it, `language` to choose which name each place is labeled
+with, and `tiles` and `glyphs` to use your own tile server.
+
+Pass `font` to draw the labels in your theme's typeface. MapLibre draws the
+letters in the page from the font your page has loaded, so there are no glyph
+files to fetch. `mapFontFrom(frame)` reads the typeface from your theme, and
+`fontReady(font)` waits until its weights are loaded. Wait for it before you
+create the map, because MapLibre keeps each letter as first drawn:
+
+```js
+const font = mapFontFrom(frame)
+await fontReady(font)
+const map = new maplibregl.Map({ container: 'map', style: mapLibreStyle(colors, { font }) })
+```
+
+The style draws the world as a globe when the map is zoomed out. The globe turns
+into the flat map as the map zooms in. `connectMap` hides markers on the far side
+of the globe, and a keyboard user who moves to one turns the globe to show it.
+Pass `globe: false` for a flat map at every zoom. MapLibre 4 has no globe, so
+pass it there too.
+
+`followTheme(map, frame, style)` restyles the map when your theme changes. It
+watches for a new color mode, class, or theme value on the frame or its
+ancestors, and for a change in the system's light or dark setting. If your page
+changes its theme another way, such as by replacing a stylesheet, call
+`update()` on the object `followTheme` returns.
+
+`colorsReady(frame)` waits until your theme's colors can be read, which can take
+a frame or two after the page loads. If the colors never become available, it
+reports which one is missing.
+
+## What you can add to a map
+
+| Element | What it adds |
+|---|---|
+| `helix-map-marker` | A named place on the map |
+| `helix-map-route` | A line, such as a delivery route |
+| `helix-map-area` | A shape, such as a delivery zone |
+| `helix-map-position` | A moving point or arrow, such as a vehicle |
+| `helix-map-points` | Thousands of places loaded from GeoJSON |
+| `helix-map-buildings` | The map's buildings, raised to their heights in 3D |
+| `helix-map-raster` | Map tiles over the map, such as weather radar or satellite imagery |
+| `helix-map-terrain` | Hills and mountains, shaded and raised in 3D |
+| `helix-map-contours` | Contour lines, each at one height |
+| `helix-map-landcover` | What covers the ground: forest, grass, farmland, sand, rock, and ice |
+
+Each element takes `tone`, such as `primary` or `danger`, for its color.
+
+### Markers
+
+```html
+<helix-map-marker
+  label="Texas Capitol"
+  lat="30.2747"
+  lng="-97.7405"
+  shape="ring"
+>
+  <span slot="icon">B</span>
+</helix-map-marker>
+```
+
+A marker is a button placed at its latitude and longitude. Its `label` appears
+when you hover over or focus the marker. The `icon` slot holds a letter, a
+number, or an icon, and `shape` sets the marker's form: `ring`, `rounded`,
+`square`, `diamond`, or `pin`. Pressing a marker sends `helix-activate` from the
+frame with the marker's `name`, or its `label` if it has no name.
+
+To show that a place has been visited, add `passed`. The marker is drawn in a
+muted color, and screen readers hear its name followed by "passed". Use
+`passed-label` to change that word.
+
+### Clusters
+
+Add `cluster` to the frame to combine markers that would overlap into one
+count. The count splits apart as you zoom in, and pressing it zooms in to its
+places. Places at the same location, such as two businesses at one address,
+spread out around that point when you press their count. Press Escape to
+combine them again.
+
+To handle a pressed cluster yourself, for example by listing its places in a
+panel, pass `clusterZoom: false` to `connectMap` and listen for
+`helix-map-cluster`.
+
+### Routes and areas
+
+```html
+<helix-map-route
+  description="4.2 km"
+  label="Depot to Mission"
+  points="37.7955,-122.3937 37.7644,-122.427"
+  progress="0.4"
+></helix-map-route>
+```
+
+Write `points` as `lat,lng` pairs separated by spaces. A route draws straight
+lines between its points, so to follow streets, pass the path from a routing
+service such as OSRM or Valhalla.
+
+- `progress`, from 0 to 1, draws the part already traveled in a lighter color.
+- `variant="dotted"` draws a route as dots, for a walk off the road network.
+- `distancesAlong(points)` measures a route the same way the connector does, so
+  something you move along the route and the lighter part stay in step.
+
+### Live positions
+
+```html
+<helix-map-position
+  accuracy="30"
+  description="Two stops away"
+  heading="90"
+  label="Van 12"
+  lat="37.78"
+  lng="-122.41"
+></helix-map-position>
+```
+
+Update `lat`, `lng`, and `heading` as the position moves. `heading` turns it
+into an arrow, and `accuracy` draws a ring with a radius of that many meters. Screen
+readers announce its `description` when it changes, at most once every
+`announce-every` milliseconds. Its movement is not announced.
+
+### Thousands of points
+
+```html
+<helix-map-points
+  cluster
+  label="Food and drink"
+  src="/places.geojson"
+></helix-map-points>
+```
+
+Use `helix-map-points` for more places than markers can handle. MapLibre draws
+all of them as one layer, loaded from a GeoJSON file in `src` or from data you
+set on `data`. With `cluster`, nearby points combine into counts, and pressing a
+count zooms in to it. Pressing a point sends `helix-activate` from the layer
+with the point's id, or with the property named by `name-key`. Leaflet draws
+each point on its own, which works for hundreds of points.
+
+### Buildings in 3D
+
+```html
+<helix-map-buildings></helix-map-buildings>
+```
+
+`helix-map-buildings` raises the buildings in the map's tiles to the heights the
+tiles record, in your theme's raised surface color. Set `tone` to color them by
+meaning. The buildings appear from zoom 13. To see their height, tilt the map by
+setting `pitch` when you create it:
+
+```js
+const map = new maplibregl.Map({ container: 'map', pitch: 55, style, zoom: 15.5 })
+```
+
+To let users tilt the map, add `tilt` to the frame's `controls`:
+
+```html
+<helix-map
+  controls="zoom compass tilt fullscreen"
+  label="Downtown Austin in 3D"
+>
+```
+
+The 3D button is a toggle. Pressed, it tilts the map 50 degrees toward the
+horizon and raises the buildings. Pressed again, it makes the map flat, and the
+buildings are the map's own flat footprints. Raised terrain lies flat with them,
+and keeps its shading. The compass's needle points north as the map turns, and
+pressing the compass turns the map back to north.
+
+Leaflet draws maps flat and does not rotate, so a Leaflet map shows no
+buildings, and the compass and the 3D button do nothing.
+
+### Weather and other tile overlays
+
+```html
+<helix-map-raster
+  attribution="Radar from Example Weather"
+  frames="https://tiles.example/radar-50m/{z}/{x}/{y}.png https://tiles.example/radar-now/{z}/{x}/{y}.png"
+  label="Weather radar"
+></helix-map-raster>
+```
+
+`helix-map-raster` draws map tiles over the land and roads, and under your
+routes, areas, and place names. Set `src` to one tile URL, or `frames` to
+several, and set `playing` to show the frames in order, `interval` milliseconds
+each. Every frame's tiles load once, so the loop plays without a blank frame.
+
+- Put the tile provider's credit in `attribution`. The frame shows it beside
+  the map's credit.
+- The frames do not play while the user has asked for reduced motion.
+- Content that moves for more than five seconds needs a way to pause it, so
+  give `playing` a control on your page.
+
+### Satellite imagery and map types
+
+```html
+<helix-map-raster
+  attribution="Imagery from USGS The National Map"
+  ground
+  label="Satellite imagery"
+  max-zoom="16"
+  opacity="1"
+  src="https://basemap.nationalmap.gov/arcgis/rest/services/USGSImageryOnly/MapServer/tile/{z}/{y}/{x}"
+></helix-map-raster>
+```
+
+Set `ground` on `helix-map-raster` to make its tiles the map's imagery. Imagery
+is a map type, which the frame's `map-type` attribute chooses:
+
+- Absent, the Standard map: your themed map, without the imagery.
+- `hybrid`: the imagery in place of the map's land, under its roads and names.
+- `satellite`: the imagery alone, without the roads and names.
+
+With `layers` in the frame's `controls`, the layers menu opens with a card for
+each map type, showing a picture of the map in it. Set `max-zoom` to the deepest
+zoom your provider has tiles for, and the map enlarges those tiles when a user
+zooms in further.
+
+The imagery above is from the U.S. Geological Survey. It is in the public domain
+and covers the United States. Some providers put `{y}` before `{x}` in their
+tile URLs, as this one does.
+
+### Terrain
+
+```html
+<helix-map-terrain
+  attribution="Elevation from 3DEP and SRTM data, courtesy of the U.S. Geological Survey"
+  max-zoom="15"
+  raised
+  src="https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png"
+></helix-map-terrain>
+```
+
+`helix-map-terrain` shades the land by its slopes, so hills and valleys show on a
+flat map. Set `raised` to raise the ground to its real height as well, and tilt
+the map to see it. Set `exaggeration` to raise it more than its real height,
+such as `1.5`. Routes, areas, and buildings lie on the raised ground.
+
+The elevation tiles above are Terrain Tiles on AWS, which are free to use and
+cover the world. Their tiles store heights in the `terrarium` encoding, which is
+the default. For tiles in the Mapbox encoding, set `encoding="mapbox"`. Credit
+the sources your map shows: in the United States, the U.S. Geological Survey.
+
+Leaflet draws maps flat, so a Leaflet map shows no terrain.
+
+### Contour lines
+
+```html
+<helix-map-contours
+  max-zoom="15"
+  src="https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png"
+  unit="feet"
+></helix-map-contours>
+```
+
+`helix-map-contours` draws lines of equal height from the same elevation tiles
+as terrain. The lines are closer together as the map zooms in, from 500 meters
+apart over a region to 5 meters at street level. Every fifth line is heavier and
+labeled with its height, in meters, or in feet with `unit="feet"`. They show
+from zoom 9, and lie on the ground when it is raised.
+
+### Land cover
+
+```html
+<helix-map-landcover></helix-map-landcover>
+```
+
+`helix-map-landcover` colors the ground by what covers it: forest and grass in
+greens, farmland in wheat, wetland in teal, sand in tan, rock in gray, and ice
+in pale blue. Each color is mixed into your theme's land color. It draws over
+parks and under water and roads, so a park shows its meadows and forests.
+
+### Turn layers on and off
+
+```html
+<helix-map
+  controls="zoom compass layers fullscreen"
+  label="Downtown Austin"
+>
+```
+
+Add `layers` to the frame's `controls` for a layers button. It opens a menu with
+a tile for each layer: a picture of what the layer draws, and its `label`. A
+tile is lit while its layer is shown. Pressing a tile sets its layer's `hidden`
+attribute, and `connectMap` does not draw a hidden layer. Write `hidden` on a
+layer to start it turned off.
+
+Give layers the same `group` to show them as one tile, such as a route and the
+dotted legs at its ends. The tile takes the name of the first layer in the
+group, and shows or hides every layer in it. Keep labels short, such as
+"Walking route", and put the rest in `description`, which screen readers read
+after the label.
+
+## Keyboard and screen readers
+
+- The frame is one tab stop. Arrow keys pan the map, and the plus and minus keys
+  zoom it. Shift with Left or Right rotates the map, and Shift with Up or Down
+  tilts it.
+- The markers are one tab stop. Arrow keys move between them in the order you
+  wrote them. The map pans to show a marker that is off screen.
+- A points layer is one tab stop over the points and counts in view. Arrow keys
+  move top to bottom and along each line. Enter on a count zooms in to it.
+- Screen readers find the map's shown layers in a list inside the frame, named
+  by their `label` and `description`.
+- With a pointer, dragging is the only way to move and turn the map. Where your
+  map has to work without dragging, as WCAG 2.2 asks at level AA, add `pan` and
+  `rotate` to `controls` for buttons around the compass that move and turn it.
+- In the layers menu, Tab moves between the tiles, Space or Enter turns a layer
+  on or off, and Escape closes the menu.
+
+## Write a driver
+
+To use another renderer, write a driver: an object with two methods.
+
+- `panBy(x, y, motion)` moves the map by a number of pixels.
+- `zoomBy(direction, motion)` zooms in for `1` and out for `-1`.
+
+`motion` is your theme's `{ duration, easing }`, or `null` to move without
+animation. Each optional method turns on a feature:
+
+| Method | Turns on |
+|---|---|
+| `project`, `onView` | Placing markers and positions |
+| `show` | Bringing a focused marker into view |
+| `fit` | `connection.fit()` and zooming in to clusters |
+| `layers` | Drawing routes, areas, and points |
+| `credits` | The map credit in the frame's footer |
+| `silenceKeyboard`, `focusTarget`, `replaceZoom` | Using the frame's keys and zoom buttons |
+| `bearing` | Arrows that stay correct when the map is rotated, and the Face north arrow |
+| `rotate`, `tilt` | The rotate, Face north, and tilt buttons and keys |
+
+Without `project`, markers stay hidden. To animate a move your page makes
+itself, read the same motion with `motionOf(element, pace)`.