@fusion.dev/helix-docs 0.114.0 → 0.116.0

package/content/maps.mdx

@@ -227,6 +227,35 @@ 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.
 
+## Share the scroll with the page
+
+By default a map takes every gesture over it: the wheel zooms the map, and one
+finger pans it. That suits a map that is the page, such as a full-screen view.
+A map embedded in a page, such as a hero, takes the wheel from a reader who is
+scrolling past it. Set `gestures` on the frame to share them:
+
+```html
+<helix-map gestures="cooperative" label="Downtown Austin">
+  <div id="map"></div>
+</helix-map>
+```
+
+- `cooperative` leaves the wheel and one finger to the page. The map takes Ctrl
+  or ⌘ with the wheel, and two fingers. When a gesture passes to the page, the
+  frame says how to reach the map, where the gesture was. Use it for a map
+  embedded in a page.
+- `activate` takes nothing until the map is pressed. The frame then shows that
+  the map has the gestures, and gives them back when the reader presses Escape,
+  moves the pointer off the map, or presses elsewhere on the page.
+- `always`, the default, takes every gesture.
+
+The keyboard and the frame's buttons work the same in every mode. `connectMap`
+tells the renderer, so MapLibre and Leaflet behave alike, and MapLibre's own
+message is replaced by the frame's. For Leaflet, pass `L`, as
+`leafletDriver(map, L)`. Change the words with `wheel-hint-label`,
+`two-finger-hint-label`, `activate-hint-label`, and `using-label`. Style the
+hint and the line with `::part(gesture-hint)` and `::part(gesture-status)`.
+
 ## Show the map once it is drawn
 
 MapLibre draws a map in stages: the streets, then the imagery tile by tile,
@@ -325,6 +354,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

package/content/metrics.mdx

@@ -58,10 +58,10 @@ either barrel. The per-component tables show what your page pays.
 | Package | Raw | Gzip | Brotli | |
 |---|---|---|---|---|
 | `@fusion.dev/helix-core` | 177,240 | 56,685 | 48,188 | The element base class, mixins, decorators, and floating positioning. |
-| `@fusion.dev/helix-headless` | 726,527 | 188,207 | 146,254 | Every headless family. The barrel entry includes all of them. |
+| `@fusion.dev/helix-headless` | 730,340 | 189,029 | 147,027 | Every headless family. The barrel entry includes all of them. |
 | `@fusion.dev/helix-icons` | 55,565 | 17,727 | 14,864 | The whole glyph set. |
 | `@fusion.dev/helix-theme` | 3,626 | 1,597 | 1,384 | The derivation engine. Most sites run it at build time, and a theme switcher runs it in the browser. |
-| `@fusion.dev/helix` | 1,259,455 | 294,753 | 216,500 | Every styled family. |
+| `@fusion.dev/helix` | 1,264,143 | 295,868 | 217,227 | Every styled family. |
 | `lit` | 15,394 | 6,118 | 5,460 | Lit itself, listed so you can subtract it from every row above. |
 
 ## Stylesheets
@@ -84,9 +84,9 @@ shows the whole cost of using the base layer on its own.
 
 **Most of your first component is the shared runtime.** The median styled family is 20,629 bytes gzipped alone, and it adds 2,221 to a page that already has Helix. The shared runtime is 89 percent of the first component, and the component itself is 11 percent. Ten typical components cost the first number once, plus nine of the added number. The two columns in the tables below let you work that out for your own components.
 
-Across the 103 styled components, the smallest is `code` at 9,802 bytes gzipped alone, and the largest is `data-table` at 63,637. Every family together is 294,753.
+Across the 103 styled components, the smallest is `code` at 9,802 bytes gzipped alone, and the largest is `data-table` at 63,637. Every family together is 295,868.
 
-No family imports a barrel. The `barrels` rule in `fusion workspace` enforces that. `@fusion.dev/helix-headless` marks every module in `dist` as having side effects, which is true of a file that calls `customElements.define`. A bundler can remove none of it. One `import { HelixHeadlessButton } from '@fusion.dev/helix-headless'` costs 188,207 bytes gzipped, whatever else the page imports. That is 9 times the median family above. All 103 styled families import the headless family they extend directly. The rule checks the shape of the import, so it applies to any package that sets `sideEffects`, whatever its name.
+No family imports a barrel. The `barrels` rule in `fusion workspace` enforces that. `@fusion.dev/helix-headless` marks every module in `dist` as having side effects, which is true of a file that calls `customElements.define`. A bundler can remove none of it. One `import { HelixHeadlessButton } from '@fusion.dev/helix-headless'` costs 189,029 bytes gzipped, whatever else the page imports. That is 9 times the median family above. All 103 styled families import the headless family they extend directly. The rule checks the shape of the import, so it applies to any package that sets `sideEffects`, whatever its name.
 
 The headless tier never had the problem, so it serves as the control. `@fusion.dev/helix-core` is `sideEffects: false`, and the median headless family is 21,082 bytes gzipped alone.
 
@@ -230,7 +230,7 @@ Structure, accessibility, state, and form participation. It has no presentation
 | `list` | 32,717 | 10,112 | 8,882 | 1,726 | 351 | 261 |
 | `listbox` | 107,105 | 34,377 | 27,998 | 11,262 | 3,083 | 2,411 |
 | `loader` | 31,901 | 10,048 | 8,837 | 900 | 227 | 50 |
-| `map` | 127,184 | 38,398 | 31,806 | 32,551 | 7,567 | 6,138 |
+| `map` | 130,997 | 39,371 | 32,568 | 36,365 | 8,484 | 6,943 |
 | `megamenu` | 62,159 | 20,749 | 18,373 | 4,941 | 1,351 | 966 |
 | `menu` | 125,881 | 41,816 | 35,009 | 8,855 | 2,228 | 1,664 |
 | `meter` | 35,091 | 10,894 | 9,614 | 4,099 | 1,059 | 815 |
@@ -337,7 +337,7 @@ The headless tier plus presentation. `bun add @fusion.dev/helix` installs this t
 | `list` | 36,783 | 11,064 | 9,720 | 5,782 | 1,298 | 1,049 |
 | `listbox` | 111,622 | 35,424 | 28,887 | 15,768 | 4,115 | 3,277 |
 | `loader` | 35,067 | 10,812 | 9,512 | 4,051 | 995 | 760 |
-| `map` | 162,545 | 43,764 | 36,429 | 67,896 | 13,040 | 10,771 |
+| `map` | 167,235 | 44,872 | 37,264 | 72,588 | 14,039 | 11,630 |
 | `megamenu` | 67,040 | 21,815 | 19,332 | 9,805 | 2,410 | 1,905 |
 | `menu` | 133,408 | 43,467 | 36,434 | 16,362 | 3,837 | 3,129 |
 | `meter` | 40,489 | 12,037 | 10,612 | 9,479 | 2,219 | 1,827 |
@@ -398,12 +398,12 @@ stripped column shows the bytes we removed.
 
 | Package | Unpacked | Files | Source maps stripped | Runtime dependencies |
 |---|---|---|---|---|
-| `@fusion.dev/helix-core` | 1,145,832 | 169 | 254,745 | `@floating-ui/dom`, `@fusion.dev/helix-icons` |
-| `@fusion.dev/helix-headless` | 13,176,137 | 504 | 1,051,621 | `@fusion.dev/helix-core`, `@fusion.dev/helix-icons`, `uqr` |
+| `@fusion.dev/helix-core` | 1,145,925 | 169 | 254,756 | `@floating-ui/dom`, `@fusion.dev/helix-icons` |
+| `@fusion.dev/helix-headless` | 13,213,764 | 504 | 1,057,948 | `@fusion.dev/helix-core`, `@fusion.dev/helix-icons`, `uqr` |
 | `@fusion.dev/helix-icons` | 150,162 | 21 | 50,346 | `svgo` |
 | `@fusion.dev/helix-styles` | 102,108 | 6 | 0 | none |
 | `@fusion.dev/helix-theme` | 500,416 | 8 | 5,191 | none |
-| `@fusion.dev/helix` | 14,313,272 | 870 | 371,466 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
+| `@fusion.dev/helix` | 14,344,183 | 870 | 371,503 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
 
 ## Not measured yet
 

package/dist/sources.generated.js

@@ -2506,6 +2506,35 @@ 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.
 
+## Share the scroll with the page
+
+By default a map takes every gesture over it: the wheel zooms the map, and one
+finger pans it. That suits a map that is the page, such as a full-screen view.
+A map embedded in a page, such as a hero, takes the wheel from a reader who is
+scrolling past it. Set \`gestures\` on the frame to share them:
+
+\`\`\`html
+<helix-map gestures="cooperative" label="Downtown Austin">
+  <div id="map"></div>
+</helix-map>
+\`\`\`
+
+- \`cooperative\` leaves the wheel and one finger to the page. The map takes Ctrl
+  or ⌘ with the wheel, and two fingers. When a gesture passes to the page, the
+  frame says how to reach the map, where the gesture was. Use it for a map
+  embedded in a page.
+- \`activate\` takes nothing until the map is pressed. The frame then shows that
+  the map has the gestures, and gives them back when the reader presses Escape,
+  moves the pointer off the map, or presses elsewhere on the page.
+- \`always\`, the default, takes every gesture.
+
+The keyboard and the frame's buttons work the same in every mode. \`connectMap\`
+tells the renderer, so MapLibre and Leaflet behave alike, and MapLibre's own
+message is replaced by the frame's. For Leaflet, pass \`L\`, as
+\`leafletDriver(map, L)\`. Change the words with \`wheel-hint-label\`,
+\`two-finger-hint-label\`, \`activate-hint-label\`, and \`using-label\`. Style the
+hint and the line with \`::part(gesture-hint)\` and \`::part(gesture-status)\`.
+
 ## Show the map once it is drawn
 
 MapLibre draws a map in stages: the streets, then the imagery tile by tile,
@@ -2604,6 +2633,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
@@ -2906,10 +2958,10 @@ either barrel. The per-component tables show what your page pays.
 | Package | Raw | Gzip | Brotli | |
 |---|---|---|---|---|
 | \`@fusion.dev/helix-core\` | 177,240 | 56,685 | 48,188 | The element base class, mixins, decorators, and floating positioning. |
-| \`@fusion.dev/helix-headless\` | 726,527 | 188,207 | 146,254 | Every headless family. The barrel entry includes all of them. |
+| \`@fusion.dev/helix-headless\` | 730,340 | 189,029 | 147,027 | Every headless family. The barrel entry includes all of them. |
 | \`@fusion.dev/helix-icons\` | 55,565 | 17,727 | 14,864 | The whole glyph set. |
 | \`@fusion.dev/helix-theme\` | 3,626 | 1,597 | 1,384 | The derivation engine. Most sites run it at build time, and a theme switcher runs it in the browser. |
-| \`@fusion.dev/helix\` | 1,259,455 | 294,753 | 216,500 | Every styled family. |
+| \`@fusion.dev/helix\` | 1,264,143 | 295,868 | 217,227 | Every styled family. |
 | \`lit\` | 15,394 | 6,118 | 5,460 | Lit itself, listed so you can subtract it from every row above. |
 
 ## Stylesheets
@@ -2932,9 +2984,9 @@ shows the whole cost of using the base layer on its own.
 
 **Most of your first component is the shared runtime.** The median styled family is 20,629 bytes gzipped alone, and it adds 2,221 to a page that already has Helix. The shared runtime is 89 percent of the first component, and the component itself is 11 percent. Ten typical components cost the first number once, plus nine of the added number. The two columns in the tables below let you work that out for your own components.
 
-Across the 103 styled components, the smallest is \`code\` at 9,802 bytes gzipped alone, and the largest is \`data-table\` at 63,637. Every family together is 294,753.
+Across the 103 styled components, the smallest is \`code\` at 9,802 bytes gzipped alone, and the largest is \`data-table\` at 63,637. Every family together is 295,868.
 
-No family imports a barrel. The \`barrels\` rule in \`fusion workspace\` enforces that. \`@fusion.dev/helix-headless\` marks every module in \`dist\` as having side effects, which is true of a file that calls \`customElements.define\`. A bundler can remove none of it. One \`import { HelixHeadlessButton } from '@fusion.dev/helix-headless'\` costs 188,207 bytes gzipped, whatever else the page imports. That is 9 times the median family above. All 103 styled families import the headless family they extend directly. The rule checks the shape of the import, so it applies to any package that sets \`sideEffects\`, whatever its name.
+No family imports a barrel. The \`barrels\` rule in \`fusion workspace\` enforces that. \`@fusion.dev/helix-headless\` marks every module in \`dist\` as having side effects, which is true of a file that calls \`customElements.define\`. A bundler can remove none of it. One \`import { HelixHeadlessButton } from '@fusion.dev/helix-headless'\` costs 189,029 bytes gzipped, whatever else the page imports. That is 9 times the median family above. All 103 styled families import the headless family they extend directly. The rule checks the shape of the import, so it applies to any package that sets \`sideEffects\`, whatever its name.
 
 The headless tier never had the problem, so it serves as the control. \`@fusion.dev/helix-core\` is \`sideEffects: false\`, and the median headless family is 21,082 bytes gzipped alone.
 
@@ -3078,7 +3130,7 @@ Structure, accessibility, state, and form participation. It has no presentation
 | \`list\` | 32,717 | 10,112 | 8,882 | 1,726 | 351 | 261 |
 | \`listbox\` | 107,105 | 34,377 | 27,998 | 11,262 | 3,083 | 2,411 |
 | \`loader\` | 31,901 | 10,048 | 8,837 | 900 | 227 | 50 |
-| \`map\` | 127,184 | 38,398 | 31,806 | 32,551 | 7,567 | 6,138 |
+| \`map\` | 130,997 | 39,371 | 32,568 | 36,365 | 8,484 | 6,943 |
 | \`megamenu\` | 62,159 | 20,749 | 18,373 | 4,941 | 1,351 | 966 |
 | \`menu\` | 125,881 | 41,816 | 35,009 | 8,855 | 2,228 | 1,664 |
 | \`meter\` | 35,091 | 10,894 | 9,614 | 4,099 | 1,059 | 815 |
@@ -3185,7 +3237,7 @@ The headless tier plus presentation. \`bun add @fusion.dev/helix\` installs this
 | \`list\` | 36,783 | 11,064 | 9,720 | 5,782 | 1,298 | 1,049 |
 | \`listbox\` | 111,622 | 35,424 | 28,887 | 15,768 | 4,115 | 3,277 |
 | \`loader\` | 35,067 | 10,812 | 9,512 | 4,051 | 995 | 760 |
-| \`map\` | 162,545 | 43,764 | 36,429 | 67,896 | 13,040 | 10,771 |
+| \`map\` | 167,235 | 44,872 | 37,264 | 72,588 | 14,039 | 11,630 |
 | \`megamenu\` | 67,040 | 21,815 | 19,332 | 9,805 | 2,410 | 1,905 |
 | \`menu\` | 133,408 | 43,467 | 36,434 | 16,362 | 3,837 | 3,129 |
 | \`meter\` | 40,489 | 12,037 | 10,612 | 9,479 | 2,219 | 1,827 |
@@ -3246,12 +3298,12 @@ stripped column shows the bytes we removed.
 
 | Package | Unpacked | Files | Source maps stripped | Runtime dependencies |
 |---|---|---|---|---|
-| \`@fusion.dev/helix-core\` | 1,145,832 | 169 | 254,745 | \`@floating-ui/dom\`, \`@fusion.dev/helix-icons\` |
-| \`@fusion.dev/helix-headless\` | 13,176,137 | 504 | 1,051,621 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-icons\`, \`uqr\` |
+| \`@fusion.dev/helix-core\` | 1,145,925 | 169 | 254,756 | \`@floating-ui/dom\`, \`@fusion.dev/helix-icons\` |
+| \`@fusion.dev/helix-headless\` | 13,213,764 | 504 | 1,057,948 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-icons\`, \`uqr\` |
 | \`@fusion.dev/helix-icons\` | 150,162 | 21 | 50,346 | \`svgo\` |
 | \`@fusion.dev/helix-styles\` | 102,108 | 6 | 0 | none |
 | \`@fusion.dev/helix-theme\` | 500,416 | 8 | 5,191 | none |
-| \`@fusion.dev/helix\` | 14,313,272 | 870 | 371,466 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
+| \`@fusion.dev/helix\` | 14,344,183 | 870 | 371,503 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
 
 ## Not measured yet
 

package/package.json

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