@fusion.dev/helix-core 0.116.0 → 0.118.0

package/custom-elements.json

@@ -3775,6 +3775,116 @@
           },
           "helix": {}
         },
+        {
+          "kind": "class",
+          "description": "The reader asked the graph to move. A request, as a map's is: Helix draws no\ngraph, and the renderer the page slotted, or `connectGraph`, answers it.",
+          "name": "HelixGraphPanEvent",
+          "members": [
+            {
+              "kind": "field",
+              "name": "eventName",
+              "type": {
+                "text": "string"
+              },
+              "static": true,
+              "readonly": true,
+              "default": "'helix-graph-pan'"
+            }
+          ],
+          "superclass": {
+            "name": "CustomEvent",
+            "module": "src/events/events.ts"
+          },
+          "helix": {}
+        },
+        {
+          "kind": "class",
+          "description": "The reader asked the graph to zoom, a direction and not a level, as a map's is.",
+          "name": "HelixGraphZoomEvent",
+          "members": [
+            {
+              "kind": "field",
+              "name": "eventName",
+              "type": {
+                "text": "string"
+              },
+              "static": true,
+              "readonly": true,
+              "default": "'helix-graph-zoom'"
+            }
+          ],
+          "superclass": {
+            "name": "CustomEvent",
+            "module": "src/events/events.ts"
+          },
+          "helix": {}
+        },
+        {
+          "kind": "class",
+          "description": "A layout settled, with where it put every note. Keep the positions and hand\nthem back as each note's `x` and `y`, and the graph opens where the reader\nleft it, with no layout to run.",
+          "name": "HelixGraphLayoutEvent",
+          "members": [
+            {
+              "kind": "field",
+              "name": "eventName",
+              "type": {
+                "text": "string"
+              },
+              "static": true,
+              "readonly": true,
+              "default": "'helix-graph-layout'"
+            }
+          ],
+          "superclass": {
+            "name": "CustomEvent",
+            "module": "src/events/events.ts"
+          },
+          "helix": {}
+        },
+        {
+          "kind": "class",
+          "description": "The frame's notes, links, selection, depth or gestures changed, which the\nconnector hears and the renderer is told. It stays on the frame, being the\nfamily's own bookkeeping rather than news for a page.",
+          "name": "HelixGraphPartChangeEvent",
+          "members": [
+            {
+              "kind": "field",
+              "name": "eventName",
+              "type": {
+                "text": "string"
+              },
+              "static": true,
+              "readonly": true,
+              "default": "'helix-graph-part-change'"
+            }
+          ],
+          "superclass": {
+            "name": "CustomEvent",
+            "module": "src/events/events.ts"
+          },
+          "helix": {}
+        },
+        {
+          "kind": "class",
+          "description": "The graph has been drawn whole, laid out and settled, sent once each time it\nis connected, from the frame, which then matches `:state(ready)`.",
+          "name": "HelixGraphReadyEvent",
+          "members": [
+            {
+              "kind": "field",
+              "name": "eventName",
+              "type": {
+                "text": "string"
+              },
+              "static": true,
+              "readonly": true,
+              "default": "'helix-graph-ready'"
+            }
+          ],
+          "superclass": {
+            "name": "Event",
+            "module": "src/events/events.ts"
+          },
+          "helix": {}
+        },
         {
           "kind": "class",
           "description": "The user asked the map to rotate, from a rotate button or key. Turn your map\nin response. Not cancelable, because the frame moves nothing itself.",
@@ -4638,6 +4748,46 @@
             "module": "src/events/events.ts"
           }
         },
+        {
+          "kind": "js",
+          "name": "HelixGraphPanEvent",
+          "declaration": {
+            "name": "HelixGraphPanEvent",
+            "module": "src/events/events.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "HelixGraphZoomEvent",
+          "declaration": {
+            "name": "HelixGraphZoomEvent",
+            "module": "src/events/events.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "HelixGraphLayoutEvent",
+          "declaration": {
+            "name": "HelixGraphLayoutEvent",
+            "module": "src/events/events.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "HelixGraphPartChangeEvent",
+          "declaration": {
+            "name": "HelixGraphPartChangeEvent",
+            "module": "src/events/events.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "HelixGraphReadyEvent",
+          "declaration": {
+            "name": "HelixGraphReadyEvent",
+            "module": "src/events/events.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "HelixMapRotateEvent",
@@ -6436,6 +6586,22 @@
             "module": "./events/events.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "GraphLayoutDetail",
+          "declaration": {
+            "name": "GraphLayoutDetail",
+            "module": "./events/events.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "GraphPartChangeDetail",
+          "declaration": {
+            "name": "GraphPartChangeDetail",
+            "module": "./events/events.js"
+          }
+        },
         {
           "kind": "js",
           "name": "HelixActivateEvent",
@@ -6660,6 +6826,46 @@
             "module": "./events/events.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "HelixGraphLayoutEvent",
+          "declaration": {
+            "name": "HelixGraphLayoutEvent",
+            "module": "./events/events.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "HelixGraphPanEvent",
+          "declaration": {
+            "name": "HelixGraphPanEvent",
+            "module": "./events/events.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "HelixGraphPartChangeEvent",
+          "declaration": {
+            "name": "HelixGraphPartChangeEvent",
+            "module": "./events/events.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "HelixGraphReadyEvent",
+          "declaration": {
+            "name": "HelixGraphReadyEvent",
+            "module": "./events/events.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "HelixGraphZoomEvent",
+          "declaration": {
+            "name": "HelixGraphZoomEvent",
+            "module": "./events/events.js"
+          }
+        },
         {
           "kind": "js",
           "name": "HelixHistoryEvent",
@@ -7332,6 +7538,30 @@
             "module": "./mixins/mixin-viewport/mixin-viewport.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "ViewportGestureLabels",
+          "declaration": {
+            "name": "ViewportGestureLabels",
+            "module": "./mixins/mixin-viewport/mixin-viewport.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ViewportGestureMode",
+          "declaration": {
+            "name": "ViewportGestureMode",
+            "module": "./mixins/mixin-viewport/mixin-viewport.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ViewportGestures",
+          "declaration": {
+            "name": "ViewportGestures",
+            "module": "./mixins/mixin-viewport/mixin-viewport.js"
+          }
+        },
         {
           "kind": "js",
           "name": "ViewportWay",
@@ -8012,6 +8242,14 @@
             "module": "./utils/value-as/value-as.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "watchTheme",
+          "declaration": {
+            "name": "watchTheme",
+            "module": "./utils/watch-theme/watch-theme.js"
+          }
+        },
         {
           "kind": "js",
           "name": "writeTime",
@@ -11486,6 +11724,115 @@
               },
               "description": "The fullscreen button's label."
             },
+            {
+              "kind": "field",
+              "name": "gestures",
+              "type": {
+                "text": "'activate' | 'always' | 'cooperative' | undefined"
+              },
+              "description": "Which gestures the surface takes from the page. Unset is the family's own."
+            },
+            {
+              "kind": "field",
+              "name": "activateHintLabel",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The hint while a surface with `gestures=\"activate\"` waits to be pressed."
+            },
+            {
+              "kind": "field",
+              "name": "twoFingerHintLabel",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The hint when one finger swipes over a surface with `gestures=\"cooperative\"`."
+            },
+            {
+              "kind": "field",
+              "name": "usingLabel",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The line while a surface with `gestures=\"activate\"` has the gestures."
+            },
+            {
+              "kind": "field",
+              "name": "wheelHintLabel",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The hint when the wheel scrolls past a surface with `gestures=\"cooperative\"`, with `{key}`."
+            },
+            {
+              "kind": "field",
+              "name": "restingGestureLabels",
+              "type": {
+                "text": "ViewportGestureLabels"
+              },
+              "privacy": "protected",
+              "description": "What the surface says about its gestures where the page does not say it, which each family says for itself.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "gesturesTaken",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "protected",
+              "description": "Whether an `activate` surface has been pressed, and has the gestures."
+            },
+            {
+              "kind": "method",
+              "name": "gestureAllowed",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "Event"
+                  }
+                }
+              ],
+              "description": "Whether a gesture that started with this event is the surface's to answer."
+            },
+            {
+              "kind": "method",
+              "name": "gesturesChanged",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Says that `gestureMode` changed, for a family that tells a renderer."
+            },
+            {
+              "kind": "field",
+              "name": "handlePointerLeave",
+              "type": {
+                "text": "(event: PointerEvent) => void"
+              },
+              "privacy": "protected",
+              "description": "The pointer leaving the frame, bound by the family's own region."
+            },
+            {
+              "kind": "method",
+              "name": "renderGestures",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "TemplateResult"
+                }
+              },
+              "description": "The hint and the line in use, drawn inside the family's viewport."
+            },
             {
               "kind": "field",
               "name": "idleDelay",
@@ -11844,6 +12191,15 @@
           "description": "Grafts a pan-and-zoom surface: its controls, its keys, and the way out.\n\n**Nothing here is geographic, which is why it is here.** `Map` was written\nfirst and its frame turned out to be a surface a reader can move, fill the\nscreen with, and stop touching: a canvas of notes and a graph of nodes want\nthe same four hundred lines, and the only thing that made them Map's was\nbeing written there. Extracted before the second consumer rather than after,\nwhich is the opposite of what [#383](queue.md) had to conclude about a\ncontroller promoted ahead of one.\n\n**Nothing here moves anything, either.** Both controls ask, through an event\na family names, and the answer is the consumer's: the surface a reader is\nlooking at belongs to them, whether it is a tile renderer, a canvas or a\nforce layout. A mixin that moved the view would have to know what the view\nwas.\n\n**The controls are buttons, and that is a decision against arrow keys.** They\nwork too, but what a screen reader does with them is not ours to decide:\nmacOS passes them through, Windows readers hold them for their own reading\nmode unless a page takes `role=\"application\"`, which costs the reader their\nnormal way of reading everything else. A button is findable and operable in\nevery screen reader on every platform without that bargain.\n\n**What stays in the family is `render()`, its slots and its part\ndocumentation**, because a part named through an interpolation is one the\nmanifest cannot see: a loop over the four pan buttons would publish `pan-`\nand a consumer's `::part(pan-up)` would match nothing.",
           "name": "MixinViewport",
           "members": [
+            {
+              "kind": "field",
+              "name": "activateHintLabel",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The hint shown when a surface waiting to be pressed is scrolled or\nswiped over, with `gestures=\"activate\"`. Absent is the family's own.",
+              "attribute": "activate-hint-label"
+            },
             {
               "kind": "field",
               "name": "controls",
@@ -11883,6 +12239,15 @@
               "description": "The fullscreen button's label.",
               "attribute": "fullscreen-label"
             },
+            {
+              "kind": "field",
+              "name": "gestures",
+              "type": {
+                "text": "'activate' | 'always' | 'cooperative' | undefined"
+              },
+              "description": "Which gestures the surface takes from the page.\n\n- `always`: the surface takes the wheel and one finger, for a surface\n  that is the page, such as a full-screen view. A map rests here.\n- Unset is the family's own: `always` for a map, and for a board, a\n  drag and a pinch, with the plain wheel left to the page until the\n  board fills the screen.\n- `cooperative`: the wheel and one finger scroll the page, and the\n  surface takes Ctrl or ⌘ with the wheel, and two fingers. The frame\n  says so when a gesture passes to the page. Best for a surface embedded\n  in a page.\n- `activate`: the surface takes nothing until it is pressed, and gives it\n  back on Escape, when the pointer leaves it, or on a press elsewhere.\n\nThe keyboard and the frame's buttons work in every mode.\n\n**Unreflected and without a default**, because a default that reflected\nwould write an attribute onto every host that no server sent, and the\nhydration that followed would disagree with it.",
+              "attribute": "gestures"
+            },
             {
               "kind": "field",
               "name": "idleDelay",
@@ -11943,6 +12308,33 @@
               "description": "The pan up button's label.",
               "attribute": "pan-up-label"
             },
+            {
+              "kind": "field",
+              "name": "twoFingerHintLabel",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The hint shown when one finger swipes over a surface with\n`gestures=\"cooperative\"`. Absent is the family's own.",
+              "attribute": "two-finger-hint-label"
+            },
+            {
+              "kind": "field",
+              "name": "usingLabel",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The line shown while a surface with `gestures=\"activate\"` has the\ngestures. Absent is the family's own.",
+              "attribute": "using-label"
+            },
+            {
+              "kind": "field",
+              "name": "wheelHintLabel",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The hint shown when the wheel scrolls past a surface with\n`gestures=\"cooperative\"`, with `{key}`, which is ⌘ on a Mac and Ctrl\nelsewhere. Absent is the family's own.",
+              "attribute": "wheel-hint-label"
+            },
             {
               "kind": "field",
               "name": "zoomInLabel",
@@ -11973,6 +12365,53 @@
               "default": "false",
               "description": "Whether the surface is filling the screen."
             },
+            {
+              "kind": "field",
+              "name": "gesturesTaken",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "protected",
+              "default": "false",
+              "description": "Whether an `activate` surface has been pressed, and has the gestures."
+            },
+            {
+              "kind": "field",
+              "name": "hint",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "default": "''",
+              "description": "The hint over the surface while one shows, put there by a gesture it let pass."
+            },
+            {
+              "kind": "field",
+              "name": "hinting",
+              "type": {
+                "text": "ReturnType<typeof setTimeout> | undefined"
+              },
+              "privacy": "private",
+              "description": "When the hint goes."
+            },
+            {
+              "kind": "field",
+              "name": "hintAt",
+              "type": {
+                "text": "{ x: number; y: number } | undefined"
+              },
+              "privacy": "private",
+              "description": "Where the gesture was, in the viewport's box, which the hint is shown\nat: where the reader is looking, and on the surface wherever a page laid\nits own content over the rest of it."
+            },
+            {
+              "kind": "field",
+              "name": "takenBy",
+              "type": {
+                "text": "Event | undefined"
+              },
+              "privacy": "private",
+              "description": "The press that took the gestures, which is not also the first gesture."
+            },
             {
               "kind": "field",
               "name": "fullscreen",
@@ -12007,6 +12446,132 @@
               "description": "What the group of controls is called where the page does not say.\n\nA getter a family overrides rather than a default on the property, the\nway `restingControls` is: a default would reflect nothing and still be\none value for every family composing this.",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "restingGestureLabels",
+              "type": {
+                "text": "ViewportGestureLabels"
+              },
+              "privacy": "protected",
+              "description": "What the surface says about its gestures where the page does not say\nit, which a family overrides to name what it is: \"Press the map to use\nit\" reads better than a word that fits every surface.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "gestureAllowed",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "Event"
+                  }
+                }
+              ],
+              "description": "Whether a gesture that started with this event is the surface's to\nanswer, for a family that answers gestures itself. Never while an\n`activate` surface waits, and never on the press that ended the wait:\nthat press hands over the gestures and moves nothing."
+            },
+            {
+              "kind": "method",
+              "name": "gesturesChanged",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Says that `gestureMode` changed. Nothing here; a family whose renderer\nis told through a connector says it with its own event."
+            },
+            {
+              "kind": "method",
+              "name": "showHint",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "words",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "at",
+                  "optional": true,
+                  "type": {
+                    "text": "{ clientX: number; clientY: number }"
+                  }
+                }
+              ],
+              "description": "Shows a hint over the surface for a moment, where the gesture was."
+            },
+            {
+              "kind": "field",
+              "name": "handleGestureWheel",
+              "privacy": "private",
+              "readonly": true,
+              "description": "A wheel the surface let pass to the page, which is said: a reader\nscrolling the page past a surface that did not zoom is told why, and how\nto zoom it. **Ctrl or ⌘ with the wheel is the surface's**, and is what a\ntrackpad's pinch arrives as."
+            },
+            {
+              "kind": "field",
+              "name": "handleGestureTouch",
+              "privacy": "private",
+              "readonly": true,
+              "description": "One finger moving over the surface, which scrolls the page, and is said."
+            },
+            {
+              "kind": "field",
+              "name": "handleTake",
+              "privacy": "private",
+              "readonly": true,
+              "description": "A press on the surface itself, which hands a waiting surface the gestures."
+            },
+            {
+              "kind": "field",
+              "name": "handleGiveBackKey",
+              "privacy": "private",
+              "readonly": true,
+              "description": "Escape, which gives the page its scroll back."
+            },
+            {
+              "kind": "field",
+              "name": "handleGiveBackOutside",
+              "privacy": "private",
+              "readonly": true,
+              "description": "A press anywhere else on the page, which gives it its scroll back."
+            },
+            {
+              "kind": "field",
+              "name": "handleGiveBackBlur",
+              "privacy": "private",
+              "readonly": true,
+              "description": "The window losing focus, as a reader switching away does."
+            },
+            {
+              "kind": "field",
+              "name": "handlePointerLeave",
+              "privacy": "protected",
+              "readonly": true,
+              "description": "The pointer leaving the frame, which the family binds on its region.\n**Heard on the frame and not the drawing**, which a pointer resting on\nsomething raised over it has left. **A mouse or a pen and never a\nfinger**, whose `pointerleave` is the finger lifting: a tap took the\nsurface and gave it back in one."
+            },
+            {
+              "kind": "method",
+              "name": "renderGestures",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "TemplateResult"
+                }
+              },
+              "description": "The hint over the surface and the line while it is in use, which the\nfamily draws inside its viewport, over what was slotted. The parts are\nwritten out, as the controls' are, so the manifest sees them."
+            },
             {
               "kind": "method",
               "name": "panEvent",
@@ -12247,6 +12812,14 @@
             }
           ],
           "attributes": [
+            {
+              "name": "activate-hint-label",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The hint shown when a surface waiting to be pressed is scrolled or\nswiped over, with `gestures=\"activate\"`. Absent is the family's own.",
+              "fieldName": "activateHintLabel"
+            },
             {
               "name": "controls",
               "type": {
@@ -12280,6 +12853,14 @@
               "description": "The fullscreen button's label.",
               "fieldName": "fullscreenLabel"
             },
+            {
+              "name": "gestures",
+              "type": {
+                "text": "'activate' | 'always' | 'cooperative' | undefined"
+              },
+              "description": "Which gestures the surface takes from the page.\n\n- `always`: the surface takes the wheel and one finger, for a surface\n  that is the page, such as a full-screen view. A map rests here.\n- Unset is the family's own: `always` for a map, and for a board, a\n  drag and a pinch, with the plain wheel left to the page until the\n  board fills the screen.\n- `cooperative`: the wheel and one finger scroll the page, and the\n  surface takes Ctrl or ⌘ with the wheel, and two fingers. The frame\n  says so when a gesture passes to the page. Best for a surface embedded\n  in a page.\n- `activate`: the surface takes nothing until it is pressed, and gives it\n  back on Escape, when the pointer leaves it, or on a press elsewhere.\n\nThe keyboard and the frame's buttons work in every mode.\n\n**Unreflected and without a default**, because a default that reflected\nwould write an attribute onto every host that no server sent, and the\nhydration that followed would disagree with it.",
+              "fieldName": "gestures"
+            },
             {
               "name": "idle-delay",
               "type": {
@@ -12334,6 +12915,30 @@
               "description": "The pan up button's label.",
               "fieldName": "panUpLabel"
             },
+            {
+              "name": "two-finger-hint-label",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The hint shown when one finger swipes over a surface with\n`gestures=\"cooperative\"`. Absent is the family's own.",
+              "fieldName": "twoFingerHintLabel"
+            },
+            {
+              "name": "using-label",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The line shown while a surface with `gestures=\"activate\"` has the\ngestures. Absent is the family's own.",
+              "fieldName": "usingLabel"
+            },
+            {
+              "name": "wheel-hint-label",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The hint shown when the wheel scrolls past a surface with\n`gestures=\"cooperative\"`, with `{key}`, which is ⌘ on a Mac and Ctrl\nelsewhere. Absent is the family's own.",
+              "fieldName": "wheelHintLabel"
+            },
             {
               "name": "zoom-in-label",
               "type": {
@@ -14489,6 +15094,46 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/utils/watch-theme/watch-theme.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "watchTheme",
+          "return": {
+            "type": {
+              "text": "(() => void)"
+            }
+          },
+          "parameters": [
+            {
+              "name": "element",
+              "type": {
+                "text": "Element"
+              }
+            },
+            {
+              "name": "changed",
+              "type": {
+                "text": "() => void"
+              }
+            }
+          ],
+          "description": "Calls `changed` once a frame after anything that can move an element's\ntheme: a class, a mode, a theme's own marker or an inline token on the\nelement or any element above it, or the reader's light or dark preference.\n\n**Above it and not beside it.** A theme reaches an element only through\nthe elements it is inside, so each of those is watched for its own\nattributes and nothing below them is: a page-wide watch heard a map's own\nmarkers being placed, every frame of every pan, and threw each one away.\n\nReturns what stops watching."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "watchTheme",
+          "declaration": {
+            "name": "watchTheme",
+            "module": "src/utils/watch-theme/watch-theme.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/utils/write-time/write-time.ts",

package/dist/events/events.d.ts

@@ -558,6 +558,61 @@ export declare class HelixMapZoomEvent extends CustomEvent<ViewportZoomDetail> {
     static readonly eventName = "helix-map-zoom";
     constructor(detail: MapZoomDetail);
 }
+/**
+ * The reader asked the graph to move. A request, as a map's is: Helix draws no
+ * graph, and the renderer the page slotted, or `connectGraph`, answers it.
+ */
+export declare class HelixGraphPanEvent extends CustomEvent<ViewportPanDetail> {
+    static readonly eventName = "helix-graph-pan";
+    constructor(detail: ViewportPanDetail);
+}
+/** The reader asked the graph to zoom, a direction and not a level, as a map's is. */
+export declare class HelixGraphZoomEvent extends CustomEvent<ViewportZoomDetail> {
+    static readonly eventName = "helix-graph-zoom";
+    constructor(detail: ViewportZoomDetail);
+}
+/** Where each note was laid out, by its `id`, in the renderer's own units. */
+export interface GraphLayoutDetail {
+    positions: Record<string, {
+        x: number;
+        y: number;
+    }>;
+}
+/**
+ * A layout settled, with where it put every note. Keep the positions and hand
+ * them back as each note's `x` and `y`, and the graph opens where the reader
+ * left it, with no layout to run.
+ */
+export declare class HelixGraphLayoutEvent extends CustomEvent<GraphLayoutDetail> {
+    static readonly eventName = "helix-graph-layout";
+    constructor(detail: GraphLayoutDetail);
+}
+/** What changed on a graph frame that the renderer has to hear. */
+export interface GraphPartChangeDetail {
+    /**
+     * `data` for the notes or the links, which are drawn again; `focus` for the
+     * selected note or the depth, which change what is emphasized and shown;
+     * `gestures` for which gestures the renderer takes.
+     */
+    kind: 'data' | 'focus' | 'gestures';
+}
+/**
+ * The frame's notes, links, selection, depth or gestures changed, which the
+ * connector hears and the renderer is told. It stays on the frame, being the
+ * family's own bookkeeping rather than news for a page.
+ */
+export declare class HelixGraphPartChangeEvent extends CustomEvent<GraphPartChangeDetail> {
+    static readonly eventName = "helix-graph-part-change";
+    constructor(detail: GraphPartChangeDetail);
+}
+/**
+ * The graph has been drawn whole, laid out and settled, sent once each time it
+ * is connected, from the frame, which then matches `:state(ready)`.
+ */
+export declare class HelixGraphReadyEvent extends Event {
+    static readonly eventName = "helix-graph-ready";
+    constructor();
+}
 /** A rotate request: turn by some degrees, or turn to a bearing. */
 export interface MapRotateDetail {
     /** Degrees to turn the map clockwise. Negative turns it counterclockwise. */
@@ -1130,6 +1185,11 @@ declare const registry: {
     readonly HelixDismissEvent: typeof HelixDismissEvent;
     readonly HelixFacetEvent: typeof HelixFacetEvent;
     readonly HelixFilterEvent: typeof HelixFilterEvent;
+    readonly HelixGraphLayoutEvent: typeof HelixGraphLayoutEvent;
+    readonly HelixGraphPanEvent: typeof HelixGraphPanEvent;
+    readonly HelixGraphPartChangeEvent: typeof HelixGraphPartChangeEvent;
+    readonly HelixGraphReadyEvent: typeof HelixGraphReadyEvent;
+    readonly HelixGraphZoomEvent: typeof HelixGraphZoomEvent;
     readonly HelixHistoryEvent: typeof HelixHistoryEvent;
     readonly HelixMapClusterEvent: typeof HelixMapClusterEvent;
     readonly HelixMapPanEvent: typeof HelixMapPanEvent;

package/dist/events/events.js

@@ -252,6 +252,56 @@ export class HelixMapZoomEvent extends CustomEvent {
         });
     }
 }
+export class HelixGraphPanEvent extends CustomEvent {
+    static { this.eventName = 'helix-graph-pan'; }
+    constructor(detail) {
+        super(HelixGraphPanEvent.eventName, {
+            bubbles: true,
+            cancelable: false,
+            composed: true,
+            detail,
+        });
+    }
+}
+export class HelixGraphZoomEvent extends CustomEvent {
+    static { this.eventName = 'helix-graph-zoom'; }
+    constructor(detail) {
+        super(HelixGraphZoomEvent.eventName, {
+            bubbles: true,
+            cancelable: false,
+            composed: true,
+            detail,
+        });
+    }
+}
+export class HelixGraphLayoutEvent extends CustomEvent {
+    static { this.eventName = 'helix-graph-layout'; }
+    constructor(detail) {
+        super(HelixGraphLayoutEvent.eventName, {
+            bubbles: true,
+            cancelable: false,
+            composed: true,
+            detail,
+        });
+    }
+}
+export class HelixGraphPartChangeEvent extends CustomEvent {
+    static { this.eventName = 'helix-graph-part-change'; }
+    constructor(detail) {
+        super(HelixGraphPartChangeEvent.eventName, {
+            bubbles: false,
+            cancelable: false,
+            composed: false,
+            detail,
+        });
+    }
+}
+export class HelixGraphReadyEvent extends Event {
+    static { this.eventName = 'helix-graph-ready'; }
+    constructor() {
+        super(HelixGraphReadyEvent.eventName, { bubbles: true, cancelable: false, composed: true });
+    }
+}
 export class HelixMapRotateEvent extends CustomEvent {
     static { this.eventName = 'helix-map-rotate'; }
     constructor(detail) {
@@ -605,6 +655,11 @@ const registry = {
     HelixDismissEvent,
     HelixFacetEvent,
     HelixFilterEvent,
+    HelixGraphLayoutEvent,
+    HelixGraphPanEvent,
+    HelixGraphPartChangeEvent,
+    HelixGraphReadyEvent,
+    HelixGraphZoomEvent,
     HelixHistoryEvent,
     HelixMapClusterEvent,
     HelixMapPanEvent,

package/dist/index.d.ts

@@ -22,7 +22,7 @@ export { SourceController, type SourceHost, } from './controllers/source-control
 export { type TokenColor, TokenColorController, } from './controllers/token-color-controller/token-color-controller.js';
 export { type Rendered, VirtualizeController, type VirtualizeOptions, type Window as VirtualizeWindow, } from './controllers/virtualize-controller/virtualize-controller.js';
 export { eventsForTag, registerElementEvents } from './events/element-events.js';
-export { type CanvasView, type CaretDetail, type ChangeDetail, type CompleteDetail, type ConnectDetail, type ConsoleDetail, type CopyDetail, type CreateDetail, type DismissDetail, type FacetDetail, type FilterDetail, HelixActivateEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeMoveEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePinEvent, HelixBeforeReconnectEvent, HelixBeforeRelabelEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCanvasEditEvent, HelixCanvasPanEvent, HelixCanvasViewEvent, HelixCanvasZoomEvent, HelixCaretEvent, HelixCompleteEvent, HelixConnectEvent, HelixConsoleEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixFacetEvent, HelixFilterEvent, HelixHistoryEvent, HelixMapClusterEvent, HelixMapPanEvent, HelixMapPartChangeEvent, HelixMapReadyEvent, HelixMapRotateEvent, HelixMapTiltEvent, HelixMapZoomEvent, HelixMoveEvent, HelixNavigateEvent, HelixNextEvent, HelixPreviousEvent, HelixReadEvent, HelixReconnectEvent, HelixRelabelEvent, HelixRemoveEvent, HelixReorderEvent, HelixResizeEvent, HelixSampleEndEvent, HelixSampleStartEvent, HelixScrolledEvent, HelixSelectEvent, HelixSendEvent, HelixShortcutEvent, HelixSortEvent, HelixTourAskEvent, type MapClusterDetail, type MapPanDetail, type MapPartChangeDetail, type MapRotateDetail, type MapTiltDetail, type MapZoomDetail, type MoveDetail, type NavigateDetail, type OpenDetail, type ReadDetail, type ReconnectDetail, type RelabelDetail, type RemoveDetail, type ResizeDetail, type ScrolledDetail, type SelectDetail, type SendDetail, type ShortcutDetail, type SkipDetail, type SortDetail, type ToggleDetail, type ViewportPanDetail, type ViewportZoomDetail, } from './events/events.js';
+export { type CanvasView, type CaretDetail, type ChangeDetail, type CompleteDetail, type ConnectDetail, type ConsoleDetail, type CopyDetail, type CreateDetail, type DismissDetail, type FacetDetail, type FilterDetail, type GraphLayoutDetail, type GraphPartChangeDetail, HelixActivateEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeMoveEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePinEvent, HelixBeforeReconnectEvent, HelixBeforeRelabelEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCanvasEditEvent, HelixCanvasPanEvent, HelixCanvasViewEvent, HelixCanvasZoomEvent, HelixCaretEvent, HelixCompleteEvent, HelixConnectEvent, HelixConsoleEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixFacetEvent, HelixFilterEvent, HelixGraphLayoutEvent, HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphReadyEvent, HelixGraphZoomEvent, HelixHistoryEvent, HelixMapClusterEvent, HelixMapPanEvent, HelixMapPartChangeEvent, HelixMapReadyEvent, HelixMapRotateEvent, HelixMapTiltEvent, HelixMapZoomEvent, HelixMoveEvent, HelixNavigateEvent, HelixNextEvent, HelixPreviousEvent, HelixReadEvent, HelixReconnectEvent, HelixRelabelEvent, HelixRemoveEvent, HelixReorderEvent, HelixResizeEvent, HelixSampleEndEvent, HelixSampleStartEvent, HelixScrolledEvent, HelixSelectEvent, HelixSendEvent, HelixShortcutEvent, HelixSortEvent, HelixTourAskEvent, type MapClusterDetail, type MapPanDetail, type MapPartChangeDetail, type MapRotateDetail, type MapTiltDetail, type MapZoomDetail, type MoveDetail, type NavigateDetail, type OpenDetail, type ReadDetail, type ReconnectDetail, type RelabelDetail, type RemoveDetail, type ResizeDetail, type ScrolledDetail, type SelectDetail, type SendDetail, type ShortcutDetail, type SkipDetail, type SortDetail, type ToggleDetail, type ViewportPanDetail, type ViewportZoomDetail, } from './events/events.js';
 export { HelixElement, whenHydrated } from './helix-element/helix-element.js';
 export { HelixFormElement } from './helix-form-element/helix-form-element.js';
 export { MixinChartSource, type MixinChartSourceInterface, PALETTE, PLOT_HEIGHT, PLOT_WIDTH, seriesIndex, seriesNames, } from './mixins/mixin-chart-source/mixin-chart-source.js';
@@ -37,7 +37,7 @@ export { MixinPickerEditing, type MixinPickerEditingInterface, } from './mixins/
 export { MixinPickerField, type MixinPickerFieldInterface, } from './mixins/mixin-picker-field/mixin-picker-field.js';
 export { MixinSelectableItem, type MixinSelectableItemInterface, } from './mixins/mixin-selectable-item/mixin-selectable-item.js';
 export { MixinTokens, type MixinTokensInterface } from './mixins/mixin-tokens/mixin-tokens.js';
-export { MixinViewport, type ViewportControlsPlacement, type ViewportElement, type ViewportWay, } from './mixins/mixin-viewport/mixin-viewport.js';
+export { MixinViewport, type ViewportControlsPlacement, type ViewportElement, type ViewportGestureLabels, type ViewportGestureMode, type ViewportGestures, type ViewportWay, } from './mixins/mixin-viewport/mixin-viewport.js';
 export { anchorElement } from './utils/anchor-element/anchor-element.js';
 export { capturePointer } from './utils/capture-pointer/capture-pointer.js';
 export { closestInstance } from './utils/closest-instance/closest-instance.js';
@@ -77,5 +77,6 @@ export { tellDisclosure } from './utils/tell-disclosure/tell-disclosure.js';
 export { subscribe } from './utils/ticker/ticker.js';
 export { type HelixStatusTone, TONE_MARKS, type ToneMark, toneMark, } from './utils/tone-marks/tone-marks.js';
 export { dateAsValue, isDateValue, isTimeValue, minutesAsValue, numberAsValue, timeAsValue, valueAsDate, valueAsMinutes, valueAsNumber, valueAsTime, } from './utils/value-as/value-as.js';
+export { watchTheme } from './utils/watch-theme/watch-theme.js';
 export { writeTime } from './utils/write-time/write-time.js';
 export { writtenList, writtenNumbers } from './utils/written-list/written-list.js';

package/dist/index.js

@@ -22,7 +22,7 @@ export { SourceController, } from './controllers/source-controller/source-contro
 export { TokenColorController, } from './controllers/token-color-controller/token-color-controller.js';
 export { VirtualizeController, } from './controllers/virtualize-controller/virtualize-controller.js';
 export { eventsForTag, registerElementEvents } from './events/element-events.js';
-export { HelixActivateEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeMoveEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePinEvent, HelixBeforeReconnectEvent, HelixBeforeRelabelEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCanvasEditEvent, HelixCanvasPanEvent, HelixCanvasViewEvent, HelixCanvasZoomEvent, HelixCaretEvent, HelixCompleteEvent, HelixConnectEvent, HelixConsoleEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixFacetEvent, HelixFilterEvent, HelixHistoryEvent, HelixMapClusterEvent, HelixMapPanEvent, HelixMapPartChangeEvent, HelixMapReadyEvent, HelixMapRotateEvent, HelixMapTiltEvent, HelixMapZoomEvent, HelixMoveEvent, HelixNavigateEvent, HelixNextEvent, HelixPreviousEvent, HelixReadEvent, HelixReconnectEvent, HelixRelabelEvent, HelixRemoveEvent, HelixReorderEvent, HelixResizeEvent, HelixSampleEndEvent, HelixSampleStartEvent, HelixScrolledEvent, HelixSelectEvent, HelixSendEvent, HelixShortcutEvent, HelixSortEvent, HelixTourAskEvent, } from './events/events.js';
+export { HelixActivateEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeMoveEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePinEvent, HelixBeforeReconnectEvent, HelixBeforeRelabelEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCanvasEditEvent, HelixCanvasPanEvent, HelixCanvasViewEvent, HelixCanvasZoomEvent, HelixCaretEvent, HelixCompleteEvent, HelixConnectEvent, HelixConsoleEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixFacetEvent, HelixFilterEvent, HelixGraphLayoutEvent, HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphReadyEvent, HelixGraphZoomEvent, HelixHistoryEvent, HelixMapClusterEvent, HelixMapPanEvent, HelixMapPartChangeEvent, HelixMapReadyEvent, HelixMapRotateEvent, HelixMapTiltEvent, HelixMapZoomEvent, HelixMoveEvent, HelixNavigateEvent, HelixNextEvent, HelixPreviousEvent, HelixReadEvent, HelixReconnectEvent, HelixRelabelEvent, HelixRemoveEvent, HelixReorderEvent, HelixResizeEvent, HelixSampleEndEvent, HelixSampleStartEvent, HelixScrolledEvent, HelixSelectEvent, HelixSendEvent, HelixShortcutEvent, HelixSortEvent, HelixTourAskEvent, } from './events/events.js';
 export { HelixElement, whenHydrated } from './helix-element/helix-element.js';
 export { HelixFormElement } from './helix-form-element/helix-form-element.js';
 export { MixinChartSource, PALETTE, PLOT_HEIGHT, PLOT_WIDTH, seriesIndex, seriesNames, } from './mixins/mixin-chart-source/mixin-chart-source.js';
@@ -77,5 +77,6 @@ export { tellDisclosure } from './utils/tell-disclosure/tell-disclosure.js';
 export { subscribe } from './utils/ticker/ticker.js';
 export { TONE_MARKS, toneMark, } from './utils/tone-marks/tone-marks.js';
 export { dateAsValue, isDateValue, isTimeValue, minutesAsValue, numberAsValue, timeAsValue, valueAsDate, valueAsMinutes, valueAsNumber, valueAsTime, } from './utils/value-as/value-as.js';
+export { watchTheme } from './utils/watch-theme/watch-theme.js';
 export { writeTime } from './utils/write-time/write-time.js';
 export { writtenList, writtenNumbers } from './utils/written-list/written-list.js';

package/dist/mixins/mixin-viewport/mixin-viewport.d.ts

@@ -1,12 +1,31 @@
-import { type LitElement, nothing, type TemplateResult } from 'lit';
+import { nothing, type TemplateResult } from 'lit';
 import { FullscreenController } from '../../controllers/fullscreen-controller/fullscreen-controller.js';
 import { IdleController } from '../../controllers/idle-controller/idle-controller.js';
 import type { ViewportPanDetail, ViewportZoomDetail } from '../../events/events.js';
+import type { HelixElement } from '../../helix-element/helix-element.js';
 type Constructor<T> = new (...args: any[]) => T;
 /** Which way a press or a key asked the surface to go. */
 export type ViewportWay = 'up' | 'down' | 'start' | 'end';
 /** Where the controls sit, in the corner words the rest of the library uses. */
 export type ViewportControlsPlacement = 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+/** Which gestures a surface takes from the page. */
+export type ViewportGestures = 'activate' | 'always' | 'cooperative';
+/**
+ * Which gestures the thing drawing the surface takes right now: all of them,
+ * the cooperative set, or none, while an `activate` surface waits to be pressed.
+ */
+export type ViewportGestureMode = 'cooperative' | 'free' | 'off';
+/** The words a surface says about its gestures, where the page does not say them. */
+export interface ViewportGestureLabels {
+    /** The hint while an `activate` surface waits to be pressed. */
+    activate: string;
+    /** The hint when one finger swipes over a `cooperative` surface. */
+    twoFinger: string;
+    /** The line while an `activate` surface has the gestures. */
+    using: string;
+    /** The hint when the wheel scrolls past a `cooperative` surface, with `{key}`. */
+    wheel: string;
+}
 /**
  * The API a pan-and-zoom surface has, as TypeScript sees it.
  */
@@ -17,6 +36,30 @@ export declare class ViewportElement {
     controlsPlacement?: ViewportControlsPlacement;
     /** The fullscreen button's label. */
     fullscreenLabel: string;
+    /** Which gestures the surface takes from the page. Unset is the family's own. */
+    gestures?: ViewportGestures;
+    /** The hint while a surface with `gestures="activate"` waits to be pressed. */
+    activateHintLabel?: string;
+    /** The hint when one finger swipes over a surface with `gestures="cooperative"`. */
+    twoFingerHintLabel?: string;
+    /** The line while a surface with `gestures="activate"` has the gestures. */
+    usingLabel?: string;
+    /** The hint when the wheel scrolls past a surface with `gestures="cooperative"`, with `{key}`. */
+    wheelHintLabel?: string;
+    /** @internal Which gestures the thing drawing the surface takes right now. */
+    get gestureMode(): ViewportGestureMode;
+    /** What the surface says about its gestures where the page does not say it, which each family says for itself. */
+    protected get restingGestureLabels(): ViewportGestureLabels;
+    /** Whether an `activate` surface has been pressed, and has the gestures. */
+    protected gesturesTaken: boolean;
+    /** Whether a gesture that started with this event is the surface's to answer. */
+    protected gestureAllowed(event: Event): boolean;
+    /** Says that `gestureMode` changed, for a family that tells a renderer. */
+    protected gesturesChanged(): void;
+    /** The pointer leaving the frame, bound by the family's own region. */
+    protected handlePointerLeave: (event: PointerEvent) => void;
+    /** The hint and the line in use, drawn inside the family's viewport. */
+    protected renderGestures(): TemplateResult;
     /** How long, in milliseconds, before the header and footer hide when the user is inactive. `0` keeps them visible. */
     idleDelay: number;
     /** The pan down button's label. */
@@ -105,5 +148,5 @@ export declare class ViewportElement {
  * manifest cannot see: a loop over the four pan buttons would publish `pan-`
  * and a consumer's `::part(pan-up)` would match nothing.
  */
-export declare const MixinViewport: <T extends Constructor<LitElement>>(Base: T) => Constructor<ViewportElement> & T;
+export declare const MixinViewport: <T extends Constructor<HelixElement>>(Base: T) => Constructor<ViewportElement> & T;
 export {};

package/dist/mixins/mixin-viewport/mixin-viewport.js

@@ -8,8 +8,10 @@ import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { FullscreenController } from '../../controllers/fullscreen-controller/fullscreen-controller.js';
 import { IdleController } from '../../controllers/idle-controller/idle-controller.js';
+import { fillTemplate } from '../../utils/fill-template/fill-template.js';
 import { inlineStep } from '../../utils/inline-step/inline-step.js';
 import { isRtl } from '../../utils/is-rtl/is-rtl.js';
+const HINT_SHOWS = 1600;
 export const MixinViewport = (Base) => {
     class Viewport extends Base {
         constructor() {
@@ -24,6 +26,8 @@ export const MixinViewport = (Base) => {
             this.zoomInLabel = 'Zoom in';
             this.resting = false;
             this.filled = false;
+            this.gesturesTaken = false;
+            this.hint = '';
             this.fullscreen = new FullscreenController(this, (full) => {
                 this.filled = full;
             });
@@ -31,6 +35,61 @@ export const MixinViewport = (Base) => {
                 this.resting = resting;
             });
             this.zoomOutLabel = 'Zoom out';
+            this.handleGestureWheel = (event) => {
+                if (this.gestures === 'cooperative' && !(event.ctrlKey || event.metaKey)) {
+                    const mac = typeof navigator !== 'undefined' && navigator.userAgent.includes('Mac');
+                    const words = this.wheelHintLabel ?? this.restingGestureLabels.wheel;
+                    this.showHint(fillTemplate(words, { key: mac ? '⌘' : 'Ctrl' }), event);
+                }
+                else if (this.gestures === 'activate' && !this.gesturesTaken) {
+                    this.showHint(this.activateHintLabel ?? this.restingGestureLabels.activate, event);
+                }
+            };
+            this.handleGestureTouch = (event) => {
+                const finger = event.touches[0];
+                if (event.touches.length !== 1) {
+                    return;
+                }
+                if (this.gestures === 'cooperative') {
+                    this.showHint(this.twoFingerHintLabel ?? this.restingGestureLabels.twoFinger, finger);
+                }
+                else if (this.gestures === 'activate' && !this.gesturesTaken) {
+                    this.showHint(this.activateHintLabel ?? this.restingGestureLabels.activate, finger);
+                }
+            };
+            this.handleTake = (event) => {
+                const viewport = this.renderRoot?.querySelector?.('[part="viewport"]');
+                if (this.gestures !== 'activate' || this.gesturesTaken || !viewport) {
+                    return;
+                }
+                const path = event.composedPath();
+                const on = path.includes(viewport) ||
+                    path.some((one) => one instanceof Element && one.parentElement === this && one.slot === '');
+                if (on) {
+                    this.takenBy = event;
+                    this.gesturesTaken = true;
+                    this.hint = '';
+                }
+            };
+            this.handleGiveBackKey = (event) => {
+                if (event.key === 'Escape' && this.gesturesTaken) {
+                    this.gesturesTaken = false;
+                }
+            };
+            this.handleGiveBackOutside = (event) => {
+                if (!event.composedPath().includes(this)) {
+                    this.gesturesTaken = false;
+                }
+            };
+            this.handleGiveBackBlur = () => {
+                this.gesturesTaken = false;
+            };
+            this.handlePointerLeave = (event) => {
+                this.idle.leave();
+                if (event.pointerType !== 'touch') {
+                    this.gesturesTaken = false;
+                }
+            };
             this.handleKeydown = (event) => {
                 const target = event.target;
                 const own = target?.closest('[part="region"], [part~="controls"]');
@@ -77,6 +136,87 @@ export const MixinViewport = (Base) => {
         get restingControlsLabel() {
             return 'View controls';
         }
+        get restingGestureLabels() {
+            return {
+                activate: 'Press to use it',
+                twoFinger: 'Use two fingers to move it',
+                using: 'In use. Press Escape to scroll the page again.',
+                wheel: 'Use {key} and scroll to zoom',
+            };
+        }
+        get gestureMode() {
+            if (this.gestures === 'cooperative') {
+                return 'cooperative';
+            }
+            return this.gestures === 'activate' && !this.gesturesTaken ? 'off' : 'free';
+        }
+        gestureAllowed(event) {
+            return this.gestureMode !== 'off' && event !== this.takenBy;
+        }
+        gesturesChanged() { }
+        showHint(words, at) {
+            const box = this.renderRoot?.querySelector?.('[part="viewport"]')?.getBoundingClientRect();
+            this.hintAt =
+                at && box && box.width > 0 && box.height > 0
+                    ? { x: (at.clientX - box.left) / box.width, y: (at.clientY - box.top) / box.height }
+                    : undefined;
+            this.hint = words;
+            clearTimeout(this.hinting);
+            this.hinting = setTimeout(() => {
+                this.hint = '';
+            }, HINT_SHOWS);
+        }
+        connectedCallback() {
+            super.connectedCallback();
+            this.addEventListener('keydown', this.handleGiveBackKey);
+            this.addEventListener('pointerdown', this.handleTake);
+            this.addEventListener('touchmove', this.handleGestureTouch, { passive: true });
+            this.addEventListener('wheel', this.handleGestureWheel, { passive: true });
+        }
+        disconnectedCallback() {
+            super.disconnectedCallback();
+            this.removeEventListener('keydown', this.handleGiveBackKey);
+            this.removeEventListener('pointerdown', this.handleTake);
+            this.removeEventListener('touchmove', this.handleGestureTouch);
+            this.removeEventListener('wheel', this.handleGestureWheel);
+            clearTimeout(this.hinting);
+            this.gesturesTaken = false;
+            document.removeEventListener('pointerdown', this.handleGiveBackOutside);
+            window.removeEventListener('blur', this.handleGiveBackBlur);
+        }
+        willUpdate(changed) {
+            super.willUpdate(changed);
+            this.toggleState('using', this.gesturesTaken);
+            this.toggleState('sharing', this.gestures === 'cooperative' || (this.gestures === 'activate' && !this.gesturesTaken));
+        }
+        updated(changed) {
+            super.updated(changed);
+            if (!changed.has('gestures') && !changed.has('gesturesTaken')) {
+                return;
+            }
+            if (this.gestures !== 'activate' && this.gesturesTaken) {
+                this.gesturesTaken = false;
+            }
+            if (this.gesturesTaken) {
+                document.addEventListener('pointerdown', this.handleGiveBackOutside);
+                window.addEventListener('blur', this.handleGiveBackBlur);
+            }
+            else {
+                document.removeEventListener('pointerdown', this.handleGiveBackOutside);
+                window.removeEventListener('blur', this.handleGiveBackBlur);
+            }
+            this.gesturesChanged();
+        }
+        renderGestures() {
+            const at = this.hintAt;
+            return html `<div
+          part="gesture-hint"
+          aria-hidden="true"
+          ?hidden=${this.hint === ''}
+          style=${at ? `--_viewport-hint-x: ${(at.x * 100).toFixed(2)}%; --_viewport-hint-y: ${(at.y * 100).toFixed(2)}%` : nothing}
+        >${this.hint}</div>
+        <div part="gesture-status" aria-hidden="true" ?hidden=${!this.gesturesTaken}>${this.usingLabel ?? this.restingGestureLabels.using}</div>`;
+        }
         panEvent(_detail) {
             throw new Error(`<${this.localName}> composes MixinViewport and must implement panEvent(), the surface naming no event of its own.`);
         }
@@ -184,6 +324,9 @@ export const MixinViewport = (Base) => {
       </div>`;
         }
     }
+    __decorate([
+        property({ attribute: 'activate-hint-label' })
+    ], Viewport.prototype, "activateHintLabel", void 0);
     __decorate([
         property({ reflect: true })
     ], Viewport.prototype, "controls", void 0);
@@ -196,6 +339,9 @@ export const MixinViewport = (Base) => {
     __decorate([
         property({ attribute: 'fullscreen-label' })
     ], Viewport.prototype, "fullscreenLabel", void 0);
+    __decorate([
+        property()
+    ], Viewport.prototype, "gestures", void 0);
     __decorate([
         property({ attribute: 'idle-delay', type: Number })
     ], Viewport.prototype, "idleDelay", void 0);
@@ -214,6 +360,15 @@ export const MixinViewport = (Base) => {
     __decorate([
         property({ attribute: 'pan-up-label' })
     ], Viewport.prototype, "panUpLabel", void 0);
+    __decorate([
+        property({ attribute: 'two-finger-hint-label' })
+    ], Viewport.prototype, "twoFingerHintLabel", void 0);
+    __decorate([
+        property({ attribute: 'using-label' })
+    ], Viewport.prototype, "usingLabel", void 0);
+    __decorate([
+        property({ attribute: 'wheel-hint-label' })
+    ], Viewport.prototype, "wheelHintLabel", void 0);
     __decorate([
         property({ attribute: 'zoom-in-label' })
     ], Viewport.prototype, "zoomInLabel", void 0);
@@ -223,6 +378,15 @@ export const MixinViewport = (Base) => {
     __decorate([
         state()
     ], Viewport.prototype, "filled", void 0);
+    __decorate([
+        state()
+    ], Viewport.prototype, "gesturesTaken", void 0);
+    __decorate([
+        state()
+    ], Viewport.prototype, "hint", void 0);
+    __decorate([
+        state()
+    ], Viewport.prototype, "hintAt", void 0);
     __decorate([
         property({ attribute: 'zoom-out-label' })
     ], Viewport.prototype, "zoomOutLabel", void 0);

package/dist/utils/watch-theme/watch-theme.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Calls `changed` once a frame after anything that can move an element's
+ * theme: a class, a mode, a theme's own marker or an inline token on the
+ * element or any element above it, or the reader's light or dark preference.
+ *
+ * **Above it and not beside it.** A theme reaches an element only through
+ * the elements it is inside, so each of those is watched for its own
+ * attributes and nothing below them is: a page-wide watch heard a map's own
+ * markers being placed, every frame of every pan, and threw each one away.
+ *
+ * Returns what stops watching.
+ */
+export declare const watchTheme: (element: Element, changed: () => void) => (() => void);

package/dist/utils/watch-theme/watch-theme.js

@@ -0,0 +1,29 @@
+const above = (element) => {
+    const chain = [];
+    let at = element;
+    while (at) {
+        chain.push(at);
+        const root = at.getRootNode();
+        at = at.parentElement ?? (root instanceof ShadowRoot ? root.host : null);
+    }
+    return chain;
+};
+const THEMING = ['class', 'data-color-mode', 'data-helix-theme', 'style'];
+export const watchTheme = (element, changed) => {
+    let pending = 0;
+    const soon = () => {
+        cancelAnimationFrame(pending);
+        pending = requestAnimationFrame(() => changed());
+    };
+    const observer = new MutationObserver(soon);
+    for (const one of above(element)) {
+        observer.observe(one, { attributeFilter: THEMING, attributes: true });
+    }
+    const scheme = typeof matchMedia === 'function' ? matchMedia('(prefers-color-scheme: dark)') : null;
+    scheme?.addEventListener('change', soon);
+    return () => {
+        cancelAnimationFrame(pending);
+        observer.disconnect();
+        scheme?.removeEventListener('change', soon);
+    };
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.116.0",
+  "version": "0.118.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -34,11 +34,11 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.116.0"
+    "@fusion.dev/helix-icons": "0.118.0"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.116.0",
-    "@fusion.dev/helix-testing": "0.116.0",
+    "@fusion.dev/helix-cem": "0.118.0",
+    "@fusion.dev/helix-testing": "0.118.0",
     "@lit-labs/ssr": "^4.1.0",
     "lit": "^3.2.1"
   },