@fusion.dev/helix-docs 0.113.0 → 0.115.0

package/content/maps.mdx

@@ -193,7 +193,7 @@ licenses require the credit to stay visible, so Helix never hides it.
 `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.
+fades it out once MapLibre has drawn the map whole.
 
 ```js
 import { mapSnapshot } from '@fusion.dev/helix-map/snapshot'
@@ -227,6 +227,32 @@ 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.
 
+## Show the map once it is drawn
+
+MapLibre draws a map in stages: the streets, then the imagery tile by tile,
+then the ground rising where there is terrain. `connectMap` tells the frame when
+the map is drawn whole, with every tile the view needs and the ground in place.
+The frame then sends `helix-map-ready` and matches `:state(ready)`. Its `ready`
+property is `true` from then on, for code that runs after the event.
+
+To show a map only once it is finished, fade it in on the state:
+
+```css
+helix-map #map {
+  opacity: 0;
+  transition: opacity 0.3s;
+}
+
+helix-map:state(ready) #map {
+  opacity: 1;
+}
+```
+
+The routes and areas the frame draws are not part of "drawn whole", so a route
+that moves along its progress does not hold the map back. A page that draws its
+own map without `connectMap` calls `drawn()` on the frame when its map is
+finished.
+
 ## What you can add to a map
 
 | Element | What it adds |
@@ -299,6 +325,29 @@ service such as OSRM or Valhalla.
 - `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.
 
+An area is a shape, such as a delivery zone or a search sector. Set `caption` to
+write a few words on the map with it:
+
+```html
+<helix-map-area
+  caption="A"
+  label="Sector A"
+  points="30.2693,-97.7745 30.2693,-97.7700 30.2655,-97.7700 30.2655,-97.7745"
+  tone="success"
+></helix-map-area>
+```
+
+The caption stands inside the area, at the point furthest from its edges. Set
+`caption-placement="outside"` to stand it above the area's northernmost point
+instead, clear of what the area holds. It is drawn in the area's color, brought
+toward the theme's text color until it reaches a 4.5:1 contrast ratio against
+the map, with a halo of the map's land around it. A caption is drawn, not
+focusable, so it adds nothing to the tab order. A screen reader hears the area's
+`label` in the frame's list of layers.
+
+On Leaflet, pass `L`, as `leafletDriver(map, L)`, and the caption is drawn as a
+marker that nobody can press or reach with the keyboard.
+
 ### Live positions
 
 ```html