@fusion.dev/helix-core 0.103.2 → 0.103.3

package/custom-elements.json

@@ -5997,6 +5997,22 @@
             "module": "./events/events.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "ViewportPanDetail",
+          "declaration": {
+            "name": "ViewportPanDetail",
+            "module": "./events/events.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ViewportZoomDetail",
+          "declaration": {
+            "name": "ViewportZoomDetail",
+            "module": "./events/events.js"
+          }
+        },
         {
           "kind": "js",
           "name": "HelixElement",
@@ -6253,6 +6269,38 @@
             "module": "./mixins/mixin-tokens/mixin-tokens.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "MixinViewport",
+          "declaration": {
+            "name": "MixinViewport",
+            "module": "./mixins/mixin-viewport/mixin-viewport.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ViewportControlsPlacement",
+          "declaration": {
+            "name": "ViewportControlsPlacement",
+            "module": "./mixins/mixin-viewport/mixin-viewport.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ViewportElement",
+          "declaration": {
+            "name": "ViewportElement",
+            "module": "./mixins/mixin-viewport/mixin-viewport.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ViewportWay",
+          "declaration": {
+            "name": "ViewportWay",
+            "module": "./mixins/mixin-viewport/mixin-viewport.js"
+          }
+        },
         {
           "kind": "js",
           "name": "anchorElement",
@@ -10101,6 +10149,605 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/mixins/mixin-viewport/mixin-viewport.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "The API a pan-and-zoom surface has, as TypeScript sees it.",
+          "name": "ViewportElement",
+          "members": [
+            {
+              "kind": "field",
+              "name": "controls",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "Which of the controls the surface draws, as a list of what to keep."
+            },
+            {
+              "kind": "field",
+              "name": "controlsPlacement",
+              "type": {
+                "text": "'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | undefined"
+              },
+              "description": "Which corner the controls sit in."
+            },
+            {
+              "kind": "field",
+              "name": "fullscreenLabel",
+              "type": {
+                "text": "string"
+              },
+              "description": "What the control that fills the screen is called."
+            },
+            {
+              "kind": "field",
+              "name": "idleDelay",
+              "type": {
+                "text": "number"
+              },
+              "description": "How long the reader may be still before the chrome hides, in milliseconds."
+            },
+            {
+              "kind": "field",
+              "name": "panLabel",
+              "type": {
+                "text": "string"
+              },
+              "description": "What one pan control is called, with `{way}` filled in."
+            },
+            {
+              "kind": "field",
+              "name": "panStep",
+              "type": {
+                "text": "number"
+              },
+              "description": "How far one press moves the view, as a fraction of what is on screen."
+            },
+            {
+              "kind": "field",
+              "name": "zoomInLabel",
+              "type": {
+                "text": "string"
+              },
+              "description": "What the control that zooms in is called."
+            },
+            {
+              "kind": "field",
+              "name": "zoomOutLabel",
+              "type": {
+                "text": "string"
+              },
+              "description": "What the control that zooms out is called."
+            },
+            {
+              "kind": "method",
+              "name": "pan",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "to",
+                  "type": {
+                    "text": "ViewportWay"
+                  }
+                }
+              ],
+              "description": "Asks for the view to move, which the consumer answers."
+            },
+            {
+              "kind": "method",
+              "name": "zoom",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "by",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Asks for the view to zoom, `1` in and `-1` out."
+            },
+            {
+              "kind": "method",
+              "name": "toggleFullscreen",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Fills the screen with the surface, or comes back."
+            },
+            {
+              "kind": "field",
+              "name": "resting",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "protected",
+              "description": "Whether the reader has been still long enough to hide the chrome."
+            },
+            {
+              "kind": "field",
+              "name": "filled",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "protected",
+              "description": "Whether the surface is filling the screen."
+            },
+            {
+              "kind": "field",
+              "name": "idle",
+              "type": {
+                "text": "IdleController"
+              },
+              "privacy": "protected",
+              "readonly": true,
+              "description": "How long the reader has been still, which the family's own frame stirs."
+            },
+            {
+              "kind": "field",
+              "name": "fullscreen",
+              "type": {
+                "text": "FullscreenController"
+              },
+              "privacy": "protected",
+              "readonly": true,
+              "description": "Into the screen and back, for a family that offers its own way in."
+            },
+            {
+              "kind": "field",
+              "name": "handleKeydown",
+              "type": {
+                "text": "(event: KeyboardEvent) => void"
+              },
+              "privacy": "protected",
+              "description": "The key relay, bound by the family's own frame."
+            },
+            {
+              "kind": "field",
+              "name": "controlsLabel",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "protected",
+              "description": "What the group of controls is called, for a family that is not a map.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "panEvent",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "Event"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "detail",
+                  "type": {
+                    "text": "ViewportPanDetail"
+                  }
+                }
+              ],
+              "description": "The pan event, built and not dispatched, for a family that names its own."
+            },
+            {
+              "kind": "method",
+              "name": "zoomEvent",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "Event"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "detail",
+                  "type": {
+                    "text": "ViewportZoomDetail"
+                  }
+                }
+              ],
+              "description": "The zoom event, built and not dispatched, for a family that names its own."
+            },
+            {
+              "kind": "method",
+              "name": "renderControls",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "TemplateResult | typeof nothing"
+                }
+              },
+              "description": "The controls, or nothing where the surface keeps none of them."
+            }
+          ],
+          "helix": {}
+        },
+        {
+          "kind": "mixin",
+          "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": "controls",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "Which of the controls this surface draws, as a list of what to keep.\n\n**A list rather than a switch, because the overlap is not symmetric.** A\nsurface a consumer brings often has zoom controls of its own and almost\nnever has pan buttons, so a single switch would make them choose between\na duplicate and nothing.\n\n`none` draws none of them, which is the right answer where what was\nslotted already has controls a reader can find: what this argues for is\nthat *a* findable control exists, never that it is ours. The methods stay\npublic either way, so a consumer drawing their own chrome can still drive\nthe surface.\n\nAbsent is all three, which is this library's rule that a resting value is\nan attribute's absence, and it is what the stylesheet asks about: the\nlayout rules are written against `[controls]:not([controls~=\"zoom\"])`\nrather than the bare negation, or a surface that named no list at all\nwould be laid out as though it had dropped everything.",
+              "attribute": "controls",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "controlsPlacement",
+              "type": {
+                "text": "'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | undefined"
+              },
+              "description": "Which corner the controls sit in.\n\n**Configurable because there is no safe default**, which is a collision\nrather than a taste: whatever a consumer slots may put its own controls\nin any corner, and every library that draws some made this a setting for\nthe same reason.\n\nLogical corners rather than left and right, so a right-to-left page moves\nthem without a consumer writing a second rule. Absent is the top end, a\nresting value being an attribute's absence: a default that reflected\nwould write an attribute onto every host that no server sent.",
+              "attribute": "controls-placement",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "fullscreenLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Fill the screen'",
+              "description": "What the control that fills the screen is called.",
+              "attribute": "fullscreen-label"
+            },
+            {
+              "kind": "field",
+              "name": "idleDelay",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "description": "How long the reader may be still before the chrome hides, in milliseconds.\n\nZero keeps it up, which is the default: these controls are how a keyboard\nreader operates the surface, and chrome that hid itself by default would\nbe the component undoing its own argument. Set it for a display nobody\ndrives.",
+              "attribute": "idle-delay"
+            },
+            {
+              "kind": "field",
+              "name": "panLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Pan {way}'",
+              "description": "What one pan control is called, with `{way}` filled in.",
+              "attribute": "pan-label"
+            },
+            {
+              "kind": "field",
+              "name": "panStep",
+              "type": {
+                "text": "number"
+              },
+              "default": "0.25",
+              "description": "How far one press moves the view, as a fraction of what is on screen.\n\nA fraction rather than a distance, because this surface does not know the\nscale of what is inside it: a quarter of the viewport is the same gesture\nat any zoom, and a consumer who wants their own units multiplies by them.",
+              "attribute": "pan-step"
+            },
+            {
+              "kind": "field",
+              "name": "zoomInLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Zoom in'",
+              "description": "What the control that zooms in is called.",
+              "attribute": "zoom-in-label"
+            },
+            {
+              "kind": "field",
+              "name": "zoomOutLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Zoom out'",
+              "description": "What the control that zooms out is called.",
+              "attribute": "zoom-out-label"
+            },
+            {
+              "kind": "field",
+              "name": "resting",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "protected",
+              "default": "false",
+              "description": "Whether the reader has been still long enough to hide the chrome."
+            },
+            {
+              "kind": "field",
+              "name": "filled",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "protected",
+              "default": "false",
+              "description": "Whether the surface is filling the screen."
+            },
+            {
+              "kind": "field",
+              "name": "fullscreen",
+              "privacy": "protected",
+              "readonly": true,
+              "default": "new FullscreenController(this, (full) => { this.filled = full })"
+            },
+            {
+              "kind": "field",
+              "name": "idle",
+              "privacy": "protected",
+              "readonly": true,
+              "default": "new IdleController( this, () => this.idleDelay, (resting) => { this.resting = resting }, )"
+            },
+            {
+              "kind": "field",
+              "name": "controlsLabel",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "protected",
+              "description": "What the group of controls is called.\n\nA getter rather than a string in the template, so a family that is not a\nmap does not announce one. Not a property: what this group is called is a\nfact about the family rather than a choice a consumer makes per instance,\nand the labels a consumer does set are the ones on the controls\nthemselves.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "panEvent",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "Event"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "detail",
+                  "type": {
+                    "text": "ViewportPanDetail"
+                  }
+                }
+              ],
+              "description": "The pan event, built and not dispatched.\n\nA factory for the reason `MixinDismissible` has one: the surface is\nshared and the name is not. `Map` sends `helix-map-pan` because that is\nwhat a consumer of a map listens for, and the next family names its own."
+            },
+            {
+              "kind": "method",
+              "name": "zoomEvent",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "Event"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "detail",
+                  "type": {
+                    "text": "ViewportZoomDetail"
+                  }
+                }
+              ],
+              "description": "The zoom event, built and not dispatched, for the same reason."
+            },
+            {
+              "kind": "method",
+              "name": "pan",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "to",
+                  "type": {
+                    "text": "ViewportWay"
+                  }
+                }
+              ],
+              "description": "Asks for the view to move, which the consumer answers."
+            },
+            {
+              "kind": "method",
+              "name": "zoom",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "by",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Asks for the view to zoom, `1` in and `-1` out."
+            },
+            {
+              "kind": "method",
+              "name": "toggleFullscreen",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Fills the screen with the surface, or comes back."
+            },
+            {
+              "kind": "method",
+              "name": "draws",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "group",
+                  "type": {
+                    "text": "'pan' | 'zoom' | 'fullscreen'"
+                  }
+                }
+              ],
+              "description": "Whether a named group of controls is one this surface draws."
+            },
+            {
+              "kind": "method",
+              "name": "named",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "way",
+                  "type": {
+                    "text": "ViewportWay"
+                  }
+                }
+              ],
+              "description": "What one pan control is called, with the way it goes filled in.\n\nLeft and right rather than start and end, because the label is read aloud\nand a reader knows which way left is. The event keeps the reading-order\nname, which is the one a right-to-left page needs."
+            },
+            {
+              "kind": "field",
+              "name": "handleKeydown",
+              "privacy": "protected",
+              "readonly": true,
+              "description": "The arrow keys, which are the second way rather than the only one.\n\n`inlineStep` rather than a test against `ArrowLeft`, so the reader on a\nright-to-left page moves the way their text runs, which is what the pan\ncontrols say too.\n\n**Only from the surface's own frame, and that is the difference between\none move and two.** What a consumer slots may answer the arrow keys\nitself, and a press relayed from inside it moves their view once on its\nown and once more on the event this would send. The rule is the region\nand the controls rather than the whole shadow root, because a family with\nits own focusable content in there, a list of notes beside a canvas,\nwould otherwise pan the surface out from under a reader arrowing through\nit."
+            },
+            {
+              "kind": "method",
+              "name": "renderControls",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "TemplateResult | typeof nothing"
+                }
+              },
+              "description": "The controls, or nothing where a consumer kept none of them.\n\n**Written out rather than generated**, because a part name behind an\ninterpolation is a part the manifest cannot see: a loop would publish\n`pan-` and a consumer's `::part(pan-up)` would match nothing."
+            }
+          ],
+          "attributes": [
+            {
+              "name": "controls",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "Which of the controls this surface draws, as a list of what to keep.\n\n**A list rather than a switch, because the overlap is not symmetric.** A\nsurface a consumer brings often has zoom controls of its own and almost\nnever has pan buttons, so a single switch would make them choose between\na duplicate and nothing.\n\n`none` draws none of them, which is the right answer where what was\nslotted already has controls a reader can find: what this argues for is\nthat *a* findable control exists, never that it is ours. The methods stay\npublic either way, so a consumer drawing their own chrome can still drive\nthe surface.\n\nAbsent is all three, which is this library's rule that a resting value is\nan attribute's absence, and it is what the stylesheet asks about: the\nlayout rules are written against `[controls]:not([controls~=\"zoom\"])`\nrather than the bare negation, or a surface that named no list at all\nwould be laid out as though it had dropped everything.",
+              "fieldName": "controls"
+            },
+            {
+              "name": "controls-placement",
+              "type": {
+                "text": "'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | undefined"
+              },
+              "description": "Which corner the controls sit in.\n\n**Configurable because there is no safe default**, which is a collision\nrather than a taste: whatever a consumer slots may put its own controls\nin any corner, and every library that draws some made this a setting for\nthe same reason.\n\nLogical corners rather than left and right, so a right-to-left page moves\nthem without a consumer writing a second rule. Absent is the top end, a\nresting value being an attribute's absence: a default that reflected\nwould write an attribute onto every host that no server sent.",
+              "fieldName": "controlsPlacement"
+            },
+            {
+              "name": "fullscreen-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Fill the screen'",
+              "description": "What the control that fills the screen is called.",
+              "fieldName": "fullscreenLabel"
+            },
+            {
+              "name": "idle-delay",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "description": "How long the reader may be still before the chrome hides, in milliseconds.\n\nZero keeps it up, which is the default: these controls are how a keyboard\nreader operates the surface, and chrome that hid itself by default would\nbe the component undoing its own argument. Set it for a display nobody\ndrives.",
+              "fieldName": "idleDelay"
+            },
+            {
+              "name": "pan-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Pan {way}'",
+              "description": "What one pan control is called, with `{way}` filled in.",
+              "fieldName": "panLabel"
+            },
+            {
+              "name": "pan-step",
+              "type": {
+                "text": "number"
+              },
+              "default": "0.25",
+              "description": "How far one press moves the view, as a fraction of what is on screen.\n\nA fraction rather than a distance, because this surface does not know the\nscale of what is inside it: a quarter of the viewport is the same gesture\nat any zoom, and a consumer who wants their own units multiplies by them.",
+              "fieldName": "panStep"
+            },
+            {
+              "name": "zoom-in-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Zoom in'",
+              "description": "What the control that zooms in is called.",
+              "fieldName": "zoomInLabel"
+            },
+            {
+              "name": "zoom-out-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Zoom out'",
+              "description": "What the control that zooms out is called.",
+              "fieldName": "zoomOutLabel"
+            }
+          ],
+          "parameters": [
+            {
+              "name": "Base",
+              "type": {
+                "text": "T"
+              }
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "ViewportElement",
+          "declaration": {
+            "name": "ViewportElement",
+            "module": "src/mixins/mixin-viewport/mixin-viewport.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "MixinViewport",
+          "declaration": {
+            "name": "MixinViewport",
+            "module": "src/mixins/mixin-viewport/mixin-viewport.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/utils/anchor-element/anchor-element.ts",

package/dist/events/events.d.ts

@@ -70,18 +70,29 @@ export interface SkipDetail {
     /** Which way the reader asked to go. */
     to: 'next' | 'previous';
 }
-/** Detail carried by `helix-map-pan`. */
-export interface MapPanDetail {
+/**
+ * Detail carried by a pan request, `helix-map-pan` being the one Map sends.
+ *
+ * Named for the surface rather than for the map, because the surface is shared:
+ * `MixinViewport` is what asks, and a canvas or a graph asking the same question
+ * should not be importing a type with `Map` in its name. `MapPanDetail` stays as
+ * an alias, that being what a consumer of Map wrote before this was split.
+ */
+export interface ViewportPanDetail {
     /** Which way the reader asked to go, in reading order rather than compass order. */
     to: 'up' | 'down' | 'start' | 'end';
     /** How far, as a fraction of the viewport the map is drawn in. */
     by: number;
 }
-/** Detail carried by `helix-map-zoom`. */
-export interface MapZoomDetail {
+/** Detail carried by a zoom request, named for the surface for the same reason. */
+export interface ViewportZoomDetail {
     /** Which way, `1` in and `-1` out, so a consumer can multiply by their own step. */
     by: number;
 }
+/** What `ViewportPanDetail` was called when only Map had one. */
+export type MapPanDetail = ViewportPanDetail;
+/** What `ViewportZoomDetail` was called when only Map had one. */
+export type MapZoomDetail = ViewportZoomDetail;
 /** Detail carried by `helix-navigate`. */
 export interface NavigateDetail {
     /** Where the view is moving to, in whatever the component pages by. */
@@ -307,7 +318,7 @@ export declare class HelixActivateEvent extends CustomEvent<ChangeDetail> {
  * Not cancelable. Nothing here moves on its own, and an event whose
  * `preventDefault` means nothing is an event that lies about what it offers.
  */
-export declare class HelixMapPanEvent extends CustomEvent<MapPanDetail> {
+export declare class HelixMapPanEvent extends CustomEvent<ViewportPanDetail> {
     static readonly eventName = "helix-map-pan";
     constructor(detail: MapPanDetail);
 }
@@ -319,7 +330,7 @@ export declare class HelixMapPanEvent extends CustomEvent<MapPanDetail> {
  * asserting a numbering that Leaflet, MapLibre and a static tile server do not
  * agree on.
  */
-export declare class HelixMapZoomEvent extends CustomEvent<MapZoomDetail> {
+export declare class HelixMapZoomEvent extends CustomEvent<ViewportZoomDetail> {
     static readonly eventName = "helix-map-zoom";
     constructor(detail: MapZoomDetail);
 }

package/dist/index.d.ts

@@ -19,7 +19,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 CaretDetail, type ChangeDetail, type CompleteDetail, type ConsoleDetail, type CopyDetail, type CreateDetail, type DismissDetail, type FacetDetail, type FilterDetail, HelixActivateEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePinEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCaretEvent, HelixCompleteEvent, HelixConsoleEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixFacetEvent, HelixFilterEvent, HelixHistoryEvent, HelixMapPanEvent, HelixMapZoomEvent, HelixNavigateEvent, HelixNextEvent, HelixPreviousEvent, HelixReadEvent, HelixReorderEvent, HelixResizeEvent, HelixSampleEndEvent, HelixSampleStartEvent, HelixScrolledEvent, HelixSelectEvent, HelixSendEvent, HelixShortcutEvent, HelixSortEvent, HelixTourAskEvent, type MapPanDetail, type MapZoomDetail, type NavigateDetail, type OpenDetail, type ReadDetail, type ResizeDetail, type ScrolledDetail, type SelectDetail, type SendDetail, type ShortcutDetail, type SkipDetail, type SortDetail, type ToggleDetail, } from './events/events.js';
+export { type CaretDetail, type ChangeDetail, type CompleteDetail, type ConsoleDetail, type CopyDetail, type CreateDetail, type DismissDetail, type FacetDetail, type FilterDetail, HelixActivateEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePinEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCaretEvent, HelixCompleteEvent, HelixConsoleEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixFacetEvent, HelixFilterEvent, HelixHistoryEvent, HelixMapPanEvent, HelixMapZoomEvent, HelixNavigateEvent, HelixNextEvent, HelixPreviousEvent, HelixReadEvent, HelixReorderEvent, HelixResizeEvent, HelixSampleEndEvent, HelixSampleStartEvent, HelixScrolledEvent, HelixSelectEvent, HelixSendEvent, HelixShortcutEvent, HelixSortEvent, HelixTourAskEvent, type MapPanDetail, type MapZoomDetail, type NavigateDetail, type OpenDetail, type ReadDetail, 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';
@@ -34,6 +34,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 { 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';

package/dist/index.js

@@ -34,6 +34,7 @@ export { MixinPickerEditing, } from './mixins/mixin-picker-editing/mixin-picker-
 export { MixinPickerField, } from './mixins/mixin-picker-field/mixin-picker-field.js';
 export { MixinSelectableItem, } from './mixins/mixin-selectable-item/mixin-selectable-item.js';
 export { MixinTokens } from './mixins/mixin-tokens/mixin-tokens.js';
+export { MixinViewport, } 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';

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

@@ -0,0 +1,85 @@
+import { type LitElement, 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, type ViewportZoomDetail } from '../../events/events.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';
+/**
+ * The API a pan-and-zoom surface has, as TypeScript sees it.
+ */
+export declare class ViewportElement {
+    /** Which of the controls the surface draws, as a list of what to keep. */
+    controls?: string;
+    /** Which corner the controls sit in. */
+    controlsPlacement?: ViewportControlsPlacement;
+    /** What the control that fills the screen is called. */
+    fullscreenLabel: string;
+    /** How long the reader may be still before the chrome hides, in milliseconds. */
+    idleDelay: number;
+    /** What one pan control is called, with `{way}` filled in. */
+    panLabel: string;
+    /** How far one press moves the view, as a fraction of what is on screen. */
+    panStep: number;
+    /** What the control that zooms in is called. */
+    zoomInLabel: string;
+    /** What the control that zooms out is called. */
+    zoomOutLabel: string;
+    /** Asks for the view to move, which the consumer answers. */
+    pan(to: ViewportWay): void;
+    /** Asks for the view to zoom, `1` in and `-1` out. */
+    zoom(by: number): void;
+    /** Fills the screen with the surface, or comes back. */
+    toggleFullscreen(): void;
+    /** Whether the reader has been still long enough to hide the chrome. */
+    protected resting: boolean;
+    /** Whether the surface is filling the screen. */
+    protected filled: boolean;
+    /** How long the reader has been still, which the family's own frame stirs. */
+    protected readonly idle: IdleController;
+    /** Into the screen and back, for a family that offers its own way in. */
+    protected readonly fullscreen: FullscreenController;
+    /** The key relay, bound by the family's own frame. */
+    protected handleKeydown: (event: KeyboardEvent) => void;
+    /** What the group of controls is called, for a family that is not a map. */
+    protected get controlsLabel(): string;
+    /** The pan event, built and not dispatched, for a family that names its own. */
+    protected panEvent(detail: ViewportPanDetail): Event;
+    /** The zoom event, built and not dispatched, for a family that names its own. */
+    protected zoomEvent(detail: ViewportZoomDetail): Event;
+    /** The controls, or nothing where the surface keeps none of them. */
+    protected renderControls(): TemplateResult | typeof nothing;
+}
+/**
+ * Grafts a pan-and-zoom surface: its controls, its keys, and the way out.
+ *
+ * **Nothing here is geographic, which is why it is here.** `Map` was written
+ * first and its frame turned out to be a surface a reader can move, fill the
+ * screen with, and stop touching: a canvas of notes and a graph of nodes want
+ * the same four hundred lines, and the only thing that made them Map's was
+ * being written there. Extracted before the second consumer rather than after,
+ * which is the opposite of what [#383](queue.md) had to conclude about a
+ * controller promoted ahead of one.
+ *
+ * **Nothing here moves anything, either.** Both controls ask, through an event
+ * a family names, and the answer is the consumer's: the surface a reader is
+ * looking at belongs to them, whether it is a tile renderer, a canvas or a
+ * force layout. A mixin that moved the view would have to know what the view
+ * was.
+ *
+ * **The controls are buttons, and that is a decision against arrow keys.** They
+ * work too, but what a screen reader does with them is not ours to decide:
+ * macOS passes them through, Windows readers hold them for their own reading
+ * mode unless a page takes `role="application"`, which costs the reader their
+ * normal way of reading everything else. A button is findable and operable in
+ * every screen reader on every platform without that bargain.
+ *
+ * **What stays in the family is `render()`, its slots and its part
+ * documentation**, because a part named through an interpolation is one the
+ * 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 {};

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

@@ -0,0 +1,168 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+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 { HelixMapPanEvent, HelixMapZoomEvent, } from '../../events/events.js';
+import { inlineStep } from '../../utils/inline-step/inline-step.js';
+export const MixinViewport = (Base) => {
+    class Viewport extends Base {
+        constructor() {
+            super(...arguments);
+            this.fullscreenLabel = 'Fill the screen';
+            this.idleDelay = 0;
+            this.panLabel = 'Pan {way}';
+            this.panStep = 0.25;
+            this.zoomInLabel = 'Zoom in';
+            this.zoomOutLabel = 'Zoom out';
+            this.resting = false;
+            this.filled = false;
+            this.fullscreen = new FullscreenController(this, (full) => {
+                this.filled = full;
+            });
+            this.idle = new IdleController(this, () => this.idleDelay, (resting) => {
+                this.resting = resting;
+            });
+            this.handleKeydown = (event) => {
+                const target = event.target;
+                const own = target?.closest('[part="region"], [part~="controls"]');
+                if (!own || !this.renderRoot.contains(own)) {
+                    return;
+                }
+                const along = inlineStep(this, event.key);
+                if (along === 1) {
+                    event.preventDefault();
+                    this.pan('end');
+                }
+                else if (along === -1) {
+                    event.preventDefault();
+                    this.pan('start');
+                }
+                else if (event.key === 'ArrowUp') {
+                    event.preventDefault();
+                    this.pan('up');
+                }
+                else if (event.key === 'ArrowDown') {
+                    event.preventDefault();
+                    this.pan('down');
+                }
+                else if (event.key === '+' || event.key === '=') {
+                    event.preventDefault();
+                    this.zoom(1);
+                }
+                else if (event.key === '-' || event.key === '_') {
+                    event.preventDefault();
+                    this.zoom(-1);
+                }
+            };
+        }
+        get controlsLabel() {
+            return 'View controls';
+        }
+        panEvent(detail) {
+            return new HelixMapPanEvent(detail);
+        }
+        zoomEvent(detail) {
+            return new HelixMapZoomEvent(detail);
+        }
+        pan(to) {
+            this.dispatchEvent(this.panEvent({ by: this.panStep, to }));
+        }
+        zoom(by) {
+            this.dispatchEvent(this.zoomEvent({ by }));
+        }
+        toggleFullscreen() {
+            void this.fullscreen.toggle();
+        }
+        draws(group) {
+            return this.controls === undefined ? true : this.controls.split(/\s+/).includes(group);
+        }
+        named(way) {
+            const spoken = way === 'start' ? 'left' : way === 'end' ? 'right' : way;
+            return this.panLabel.replace('{way}', spoken);
+        }
+        firstUpdated(changed) {
+            super.firstUpdated(changed);
+            this.idle.stir();
+        }
+        renderControls() {
+            const pan = this.draws('pan');
+            const zoom = this.draws('zoom');
+            const fullscreen = this.draws('fullscreen');
+            if (!pan && !zoom && !fullscreen) {
+                return nothing;
+            }
+            return html `<div part="controls" role="group" aria-label=${this.controlsLabel}>
+        ${pan
+                ? html `<button part="pan-up" aria-label=${this.named('up')} type="button" @click=${() => this.pan('up')}>
+                  ↑
+                </button>
+                <button part="pan-start" aria-label=${this.named('start')} type="button" @click=${() => this.pan('start')}>
+                  ←
+                </button>
+                <button part="pan-end" aria-label=${this.named('end')} type="button" @click=${() => this.pan('end')}>
+                  →
+                </button>
+                <button part="pan-down" aria-label=${this.named('down')} type="button" @click=${() => this.pan('down')}>
+                  ↓
+                </button>`
+                : nothing}
+        ${zoom
+                ? html `<button part="zoom-in" aria-label=${this.zoomInLabel} type="button" @click=${() => this.zoom(1)}>
+                  +
+                </button>
+                <button part="zoom-out" aria-label=${this.zoomOutLabel} type="button" @click=${() => this.zoom(-1)}>
+                  −
+                </button>`
+                : nothing}
+        ${fullscreen
+                ? html `<button
+                part="fullscreen"
+                aria-label=${this.fullscreenLabel}
+                aria-pressed=${this.filled ? 'true' : 'false'}
+                type="button"
+                @click=${this.toggleFullscreen}
+              >
+                ⤢
+              </button>`
+                : nothing}
+      </div>`;
+        }
+    }
+    __decorate([
+        property({ reflect: true })
+    ], Viewport.prototype, "controls", void 0);
+    __decorate([
+        property({ attribute: 'controls-placement', reflect: true })
+    ], Viewport.prototype, "controlsPlacement", void 0);
+    __decorate([
+        property({ attribute: 'fullscreen-label' })
+    ], Viewport.prototype, "fullscreenLabel", void 0);
+    __decorate([
+        property({ attribute: 'idle-delay', type: Number })
+    ], Viewport.prototype, "idleDelay", void 0);
+    __decorate([
+        property({ attribute: 'pan-label' })
+    ], Viewport.prototype, "panLabel", void 0);
+    __decorate([
+        property({ attribute: 'pan-step', type: Number })
+    ], Viewport.prototype, "panStep", void 0);
+    __decorate([
+        property({ attribute: 'zoom-in-label' })
+    ], Viewport.prototype, "zoomInLabel", void 0);
+    __decorate([
+        property({ attribute: 'zoom-out-label' })
+    ], Viewport.prototype, "zoomOutLabel", void 0);
+    __decorate([
+        state()
+    ], Viewport.prototype, "resting", void 0);
+    __decorate([
+        state()
+    ], Viewport.prototype, "filled", void 0);
+    return Viewport;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.103.2",
+  "version": "0.103.3",
   "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.103.2"
+    "@fusion.dev/helix-icons": "0.103.3"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.103.2",
-    "@fusion.dev/helix-testing": "0.103.2",
+    "@fusion.dev/helix-cem": "0.103.3",
+    "@fusion.dev/helix-testing": "0.103.3",
     "@lit-labs/ssr": "^4.1.0",
     "lit": "^3.2.1"
   },