@fusion.dev/helix-docs 0.106.0 → 0.108.0

package/content/maps.mdx

@@ -128,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 |

package/content/metrics.mdx

@@ -403,7 +403,7 @@ stripped column shows the bytes we removed.
 | `@fusion.dev/helix-icons` | 150,162 | 21 | 50,346 | `svgo` |
 | `@fusion.dev/helix-styles` | 102,108 | 6 | 0 | none |
 | `@fusion.dev/helix-theme` | 465,413 | 8 | 4,703 | none |
-| `@fusion.dev/helix` | 14,179,532 | 868 | 362,883 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
+| `@fusion.dev/helix` | 14,185,818 | 870 | 368,333 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
 
 ## Not measured yet
 

package/content/recipes.mdx

@@ -112,14 +112,40 @@ In prose:
 
 See [Typography](./typography).
 
-If you control the Markdown renderer, map two elements to components, because
-HTML alone cannot hold what they need:
-
-- **Fenced code** to `helix-code-block`, with the fence's language as its `label`.
-  A `<pre>` has no label or copy button.
-- **Alerts** such as `> [!WARNING]` to `helix-callout`. A `<blockquote>` has no
-  tone. `NOTE` and `IMPORTANT` become `tone="info"`, `TIP` becomes `success`,
-  `WARNING` becomes `warning`, and `CAUTION` becomes `danger`.
+Two Markdown constructs need components, because HTML alone cannot hold what
+they need:
+
+- **Fenced code** becomes `helix-code-block`, with the fence's language as its
+  `label`. A `<pre>` has no label or copy button.
+- **Alerts** such as `> [!WARNING]` become `helix-callout`. A `<blockquote>` has no
+  tone. `NOTE` becomes `tone="info"`, `TIP` becomes `success`, `WARNING` becomes
+  `warning`, and `CAUTION` becomes `danger`. `IMPORTANT` has no tone. Each
+  callout is headed by its kind, as GitHub shows it.
+
+The `rehype` plugin from `@fusion.dev/helix/rehype` makes both changes in the
+tree your Markdown library has already built. It parses nothing, so your
+library, its dialect, and your sanitizing stay yours. Add it to any pipeline
+that reaches rehype, such as `remark` with `remark-rehype`, `react-markdown`, or
+MDX:
+
+```js
+import rehypeHelix from '@fusion.dev/helix/rehype'
+
+const html = await unified()
+  .use(remarkParse)
+  .use(remarkRehype)
+  .use(rehypeHelix)
+  .use(rehypeStringify)
+  .process(markdown)
+```
+
+Code that a highlighter colored before the plugin ran keeps its colors. Pass
+`fences: false` if your page draws its own code blocks, `alerts: false` to keep
+alerts as quotes, and `headings` to name each kind in your page's language.
+
+> [!NOTE]
+> The plugin changes only these two constructs. If the Markdown comes from your
+> users, sanitize it in your pipeline before the plugin runs.
 
 Prose spaces each component the same as the element it replaces.
 

package/dist/sources.generated.js

@@ -2403,6 +2403,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 |
@@ -3110,7 +3146,7 @@ stripped column shows the bytes we removed.
 | \`@fusion.dev/helix-icons\` | 150,162 | 21 | 50,346 | \`svgo\` |
 | \`@fusion.dev/helix-styles\` | 102,108 | 6 | 0 | none |
 | \`@fusion.dev/helix-theme\` | 465,413 | 8 | 4,703 | none |
-| \`@fusion.dev/helix\` | 14,179,532 | 868 | 362,883 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
+| \`@fusion.dev/helix\` | 14,185,818 | 870 | 368,333 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
 
 ## Not measured yet
 
@@ -3858,14 +3894,40 @@ In prose:
 
 See [Typography](./typography).
 
-If you control the Markdown renderer, map two elements to components, because
-HTML alone cannot hold what they need:
+Two Markdown constructs need components, because HTML alone cannot hold what
+they need:
+
+- **Fenced code** becomes \`helix-code-block\`, with the fence's language as its
+  \`label\`. A \`<pre>\` has no label or copy button.
+- **Alerts** such as \`> [!WARNING]\` become \`helix-callout\`. A \`<blockquote>\` has no
+  tone. \`NOTE\` becomes \`tone="info"\`, \`TIP\` becomes \`success\`, \`WARNING\` becomes
+  \`warning\`, and \`CAUTION\` becomes \`danger\`. \`IMPORTANT\` has no tone. Each
+  callout is headed by its kind, as GitHub shows it.
+
+The \`rehype\` plugin from \`@fusion.dev/helix/rehype\` makes both changes in the
+tree your Markdown library has already built. It parses nothing, so your
+library, its dialect, and your sanitizing stay yours. Add it to any pipeline
+that reaches rehype, such as \`remark\` with \`remark-rehype\`, \`react-markdown\`, or
+MDX:
+
+\`\`\`js
+import rehypeHelix from '@fusion.dev/helix/rehype'
+
+const html = await unified()
+  .use(remarkParse)
+  .use(remarkRehype)
+  .use(rehypeHelix)
+  .use(rehypeStringify)
+  .process(markdown)
+\`\`\`
+
+Code that a highlighter colored before the plugin ran keeps its colors. Pass
+\`fences: false\` if your page draws its own code blocks, \`alerts: false\` to keep
+alerts as quotes, and \`headings\` to name each kind in your page's language.
 
-- **Fenced code** to \`helix-code-block\`, with the fence's language as its \`label\`.
-  A \`<pre>\` has no label or copy button.
-- **Alerts** such as \`> [!WARNING]\` to \`helix-callout\`. A \`<blockquote>\` has no
-  tone. \`NOTE\` and \`IMPORTANT\` become \`tone="info"\`, \`TIP\` becomes \`success\`,
-  \`WARNING\` becomes \`warning\`, and \`CAUTION\` becomes \`danger\`.
+> [!NOTE]
+> The plugin changes only these two constructs. If the Markdown comes from your
+> users, sanitize it in your pipeline before the plugin runs.
 
 Prose spaces each component the same as the element it replaces.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-docs",
   "description": "Versioned documentation content and registry for Helix.",
-  "version": "0.106.0",
+  "version": "0.108.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -36,8 +36,8 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.106.0",
-    "@fusion.dev/helix-testing": "0.106.0",
+    "@fusion.dev/helix-cem": "0.108.0",
+    "@fusion.dev/helix-testing": "0.108.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "lit": "^3.2.1",
     "playwright": "^1.62.1"