@fusion.dev/helix-docs 0.105.0 → 0.107.0

package/content/iconography.mdx

@@ -10,12 +10,12 @@ title: Iconography
 <helix-icon name="trash"></helix-icon>
 ```
 
-Helix has 108 glyphs from Phosphor, drawn on a 256 box at Phosphor's bold
-weight. We keep Phosphor's own geometry. Rescaling to a 24 box would change the
-optical weight of every glyph, and the set would stop matching Phosphor. We use
-the bold weight because Phosphor's regular weight is a hairline beside the
-medium weight of Helix text. An icon that looks lighter than the words next to
-it does not work as a mark.
+Helix has 125 glyphs, 120 of them from Phosphor, drawn on a 256 box at
+Phosphor's bold weight. We keep Phosphor's own geometry. Rescaling to a 24 box
+would change the optical weight of every glyph, and the set would stop matching
+Phosphor. We use the bold weight because Phosphor's regular weight is a
+hairline beside the medium weight of Helix text. An icon that looks lighter than
+the words next to it does not work as a mark.
 
 ## Size and color come from the surrounding text
 
@@ -90,7 +90,7 @@ both are set, `icon` wins.
 
 `icon` also keeps your bundle small. `name` looks up glyphs in an index of the
 whole set, and no bundler can tree-shake that index. If you render one icon by
-`name`, you ship the whole set: 15 kB gzipped for 108 glyphs. With `icon`, you
+`name`, you ship the whole set: 17 kB gzipped for 125 glyphs. With `icon`, you
 ship only the glyph you import.
 
 `icon` also draws glyphs from outside this set. Anything that exports the same

package/content/maps.mdx

@@ -7,7 +7,7 @@ title: Maps
 # Maps
 
 Helix Maps puts a frame around a map drawn by MapLibre, Leaflet, or a renderer of
-your own. The frame adds pan and zoom buttons and a place for the map credit. You
+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.
@@ -25,7 +25,11 @@ 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-marker
+    label="Flagship"
+    lat="30.2672"
+    lng="-97.7431"
+  ></helix-map-marker>
 </helix-map>
 ```
 
@@ -55,8 +59,8 @@ followTheme(map, frame, style)
 
 `connectMap` links the frame to the renderer:
 
-- The frame's pan and zoom buttons and keys move the map, using your theme's
-  motion settings. The map moves without animation when a user has asked for
+- 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.
@@ -79,11 +83,41 @@ you already have. Leaflet draws routes, areas, and points only when you pass it
 - 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
@@ -94,6 +128,42 @@ changes its theme another way, such as by replacing a stylesheet, call
 a frame or two after the page loads. If the colors never become available, it
 reports which one is missing.
 
+## Draw the map before it loads
+
+`mapSnapshot(view)` draws the map on your server as an SVG, from the same tiles
+and in the same colors as `mapLibreStyle`. Put it in the frame after the element
+MapLibre draws in, and the page shows a map from its first paint. `connectMap`
+fades it out once MapLibre has drawn its tiles.
+
+```js
+import { mapSnapshot } from '@fusion.dev/helix-map/snapshot'
+
+const view = {
+  center: { lat: 30.27, lng: -97.74 },
+  height: 700,
+  pitch: 45,
+  width: 1200,
+  zoom: 14,
+}
+const snapshot = await mapSnapshot(view)
+// Inside helix-map, after <div id="map"></div>, write the snapshot's markup.
+```
+
+Give MapLibre the same `center`, `zoom`, `pitch`, and `bearing`, and the snapshot
+lines up with the map that replaces it. `width` and `height` are the box it is
+drawn for, and a smaller box shows its middle. A snapshot draws the land, water,
+parks, buildings, and roads, and leaves the labels to MapLibre. Its colors are
+your theme's tokens, so it is light or dark with the page and follows a theme
+change. It resolves to an empty string when the tiles cannot be read.
+
+In a framework that renders the markup for you, such as React, put the snapshot
+in an element that is a direct child of the frame and has the
+`data-helix-map-snapshot` attribute. `connectMap` hides that element, and leaves
+removing it to your framework.
+
+A snapshot is a flat map. A map zoomed out past about 6 is a globe in MapLibre,
+so draw snapshots of city and street views.
+
 ## What you can add to a map
 
 | Element | What it adds |
@@ -103,13 +173,23 @@ reports which one is missing.
 | `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">
+<helix-map-marker
+  label="Texas Capitol"
+  lat="30.2747"
+  lng="-97.7405"
+  shape="ring"
+>
   <span slot="icon">B</span>
 </helix-map-marker>
 ```
@@ -140,8 +220,8 @@ panel, pass `clusterZoom: false` to `connectMap` and listen for
 
 ```html
 <helix-map-route
-  label="Depot to Mission"
   description="4.2 km"
+  label="Depot to Mission"
   points="37.7955,-122.3937 37.7644,-122.427"
   progress="0.4"
 ></helix-map-route>
@@ -160,12 +240,12 @@ service such as OSRM or Valhalla.
 
 ```html
 <helix-map-position
+  accuracy="30"
+  description="Two stops away"
+  heading="90"
   label="Van 12"
   lat="37.78"
   lng="-122.41"
-  heading="90"
-  accuracy="30"
-  description="Two stops away"
 ></helix-map-position>
 ```
 
@@ -177,7 +257,11 @@ readers announce its `description` when it changes, at most once every
 ### Thousands of points
 
 ```html
-<helix-map-points label="Food and drink" src="/places.geojson" cluster></helix-map-points>
+<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
@@ -187,16 +271,176 @@ 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.
+  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 routes, areas, and points layers in a list inside the
-  frame, named by their `label` and `description`.
+- 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
 
@@ -216,7 +460,8 @@ animation. Each optional method turns on a feature:
 | `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 |
+| `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)`.