@fusion.dev/helix-docs 0.206.0 → 0.207.0

package/content/maps.mdx

@@ -124,6 +124,11 @@ 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.
 
+The tiles come from OpenFreeMap unless you pass `tiles`, and so do the glyphs
+unless you pass `glyphs` or `font`. OpenFreeMap needs no key. Your reader's
+browser requests the map's tiles and glyphs from OpenFreeMap's servers, and
+`mapSnapshot` requests its tiles from them on your 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
@@ -131,6 +136,8 @@ files to fetch. `mapFontFrom(frame)` reads the typeface from your theme, and
 create the map, because MapLibre keeps each letter as first drawn:
 
 ```js
+import { fontReady, mapFontFrom } from '@fusion.dev/helix-map'
+
 const font = mapFontFrom(frame)
 await fontReady(font)
 const map = new maplibregl.Map({ container: 'map', style: mapLibreStyle(colors, { font }) })
@@ -210,7 +217,7 @@ const view = {
   zoom: 14,
 }
 const snapshot = await mapSnapshot(view)
-// Inside helix-map, after <div id="map"></div>, write the snapshot's markup.
+// Inside helix-map, after <div id="map"></div>, write snapshot.markup.
 ```
 
 Give MapLibre the same `center`, `zoom`, `pitch`, and `bearing`, and the snapshot
@@ -218,15 +225,55 @@ 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 any tile it needs cannot be read
+change. Its `markup` is an empty string when any tile it needs cannot be read
 in time, so a snapshot is whole or absent and the map draws in its place. Each
 request is given `timeout` milliseconds, 3000 by default. Cache only a snapshot
-that is not empty.
-
-In a framework that renders the markup for you, such as React, put the snapshot
+whose `markup` is not empty.
+
+A snapshot reads OpenFreeMap's tiles from your server by default. Pass the
+`tiles` you give `mapLibreStyle` as `mapSnapshot(view, { tiles })` to read
+your own.
+
+**The snapshot carries the map credit.** Most tile licenses require the credit
+wherever the map is shown, including before MapLibre loads and on a page that
+never loads it. `markup` is the picture followed by the credit your tiles
+name, in a `<span slot="attribution">` marked `data-helix-map-credit`, so the
+frame shows the credit from the first paint. `connectMap` hides that credit
+once it writes MapLibre's, which names the same tiles.
+
+A snapshot also holds the two apart: `picture`, the map alone, and `credit`,
+the credit as runs of words and links, each `{ text }` or `{ href, text }`.
+In a framework that renders the markup for you, such as React, put `picture`
 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.
+`data-helix-map-snapshot` attribute. Write `credit` in a
+`<span slot="attribution" data-helix-map-credit>`, also a direct child of the
+frame:
+
+```jsx
+<helix-map label="Downtown Austin">
+  <div id="map" />
+  <div dangerouslySetInnerHTML={{ __html: snapshot.picture }} data-helix-map-snapshot="" />
+  {snapshot.credit.length > 0 ? (
+    <span data-helix-map-credit="" slot="attribution">
+      {snapshot.credit.map((part, index) =>
+        part.href ? (
+          <a data-link="quiet" href={part.href} key={index} rel="noopener noreferrer" target="_blank">
+            {part.text}
+          </a>
+        ) : (
+          part.text
+        ),
+      )}
+    </span>
+  ) : null}
+</helix-map>
+```
+
+`connectMap` hides both elements, and leaves removing them to your framework.
+
+A credit you slot yourself, with no `data-helix-map-credit`, wins. Write
+`picture` alone beside it. A snapshot credit already in the frame is hidden
+when `connectMap` connects.
 
 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.
@@ -304,7 +351,9 @@ finished.
 | `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, routes, areas, positions, points, and buildings take `tone`, such as
+`primary` or `danger`, for their color. Raster tiles keep their own colors, and
+terrain, contours, and landcover take theirs from your theme.
 
 ### Markers
 
@@ -319,11 +368,14 @@ Each element takes `tone`, such as `primary` or `danger`, for its color.
 </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.
+A marker is a button placed at its latitude and longitude. Its point is as
+large as the map's landmarks, in your primary color, with a dot in the middle
+and a halo of the same color around it, so your places stand out from the
+landmarks. Its `label` appears when you hover over or focus the marker. The
+`icon` slot holds a letter, a number, or an icon in place of the dot, 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