@fusion.dev/helix-headless 0.162.1 → 0.163.0

package/custom-elements.json

@@ -14410,6 +14410,22 @@
             "module": "./root/canvas-root.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "CanvasRoute",
+          "declaration": {
+            "name": "CanvasRoute",
+            "module": "./root/canvas-root.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "CanvasRouteEnds",
+          "declaration": {
+            "name": "CanvasRouteEnds",
+            "module": "./root/canvas-root.js"
+          }
+        },
         {
           "kind": "js",
           "name": "CanvasSide",
@@ -15630,7 +15646,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A board of cards and connectors, drawn by Helix. On a canvas every position\nis data that someone placed, so drawing is arithmetic over rectangles with no\nlayout to compute. `Map` takes a slotted map, because another renderer draws\nits tiles.\n\nThe format is [JSON Canvas](https://jsoncanvas.org), an open format. Each\nnode has an `x`, `y`, `width`, `height`, and a type. Each edge names the two\nnodes it joins and the sides it leaves and arrives on. A card belongs to a\ngroup when it sits inside the group's bounds.\n\nThe cards are text in the DOM, so a screen reader can read them. The family\nadds a reading order and states each card's connections as text. `order` sets\nthe reading order:\n- `spatial` bands the cards into rows.\n- `edges` follows the arrows, starting from the cards that nothing points to.\n\n**Cards move by default.** The board writes the new `x` and `y` onto the\ncard, the way an input writes its own value, and dispatches two events:\n- `helix-before-move` for every step. Cancel it to hold the positions in your\n  own state and apply them yourself.\n- `helix-move` once the move is finished.\n\nA resize dispatches the same pair with a size. Set `readonly` on the board to\nkeep every card in place, such as on a published board. Set `readonly` on one\ncard or connection to keep only that one in place.\n\nSet `snap` to a length in the document's units, such as `32`, and a card\nthat is moved or resized lands on a multiple of it. Carrying a card, a\ncorner, a connection, or the selection box near the edge of the board moves\nthe board under it, so a card can be taken to a place off screen in one\ndrag. A connection let go within 20 pixels of a card arrives at it. A\ndouble click on the empty board zooms in about that point, and Shift with a\ndouble click zooms out.\n\nKeyboard behavior:\n- One card holds the board's tab stop.\n- The arrow keys move through the cards in reading order. The card you land\n  on scrolls into view, and its connections are announced with it.\n- The card you land on is selected. Control or Command with an arrow key,\n  Home, or End moves without changing the selection, and Space adds the card\n  to the selection or takes it out, so you can select cards that are not\n  next to each other.\n- Shift with an arrow key moves the card: by 16 units, or to the next\n  multiple of `snap` where it is set. Alt with an arrow key resizes it from\n  its bottom right corner the same way.\n- The connections leaving a card are stops of their own, straight after it.\n  Enter on one moves to the card it arrives at.\n- What a key changes that a reader cannot see is said: where a card moved\n  to, its new size, how many cards are selected, and the zoom. A selected\n  card or connection says so when a reader arrives on it.\n- Control or Command with C copies the selected cards, and the connections\n  between them, as a JSON Canvas document in text, which another board or\n  an app that reads the format takes. A paste is your page's: listen for\n  `paste` on the board, read the text with `fromJsonCanvas`, and add the\n  cards it holds.\n- Control or Command with Z undoes the last move or resize the board made,\n  and with Shift, or Control with Y, makes it again. `undo()` and `redo()`\n  do the same from a script. Each asks with `helix-before-move` and tells\n  with `helix-move`, as a move does, so a board that holds its positions in\n  your state is undone through your state.\n\nEvery drag also works with clicks, as WCAG 2.5.7 requires for a pointer that\ncannot hold a button down. Click a selected card's move handle, a corner, a\ncard's connection point, or the end of a selected connection to pick it up.\nIt follows the pointer with no button held, and the next click puts it down\nwhere a drag would have. On touch, the next tap sets where it lands. Escape,\nor a press outside the board, puts it back. So a finger connects two cards\nwith three taps: the card, one of its points, and the card to connect to.\n\nConnecting and removing dispatch requests, and your code applies them:\n- Drawing from a card's handle to another card, or pressing C on one card and\n  Enter on another, dispatches `helix-connect`.\n- Delete on a card or a connection dispatches `helix-remove`. The event names\n  every connection that removing the card would leave without an end.\n\nOnce your page removes what Delete asked for, focus moves to the next stop,\nto the one before where it was the last, and to the board where none is\nleft. A focused card your page removes for its own reasons hands focus on\nthe same way, unless the reader has already moved focus somewhere else.\n\nThe board applies a move itself, because the card already exists. A\nconnection is a new element, and React discards an element the board adds to\nits markup on the next render, so you write the connection.\n\nCards and connections are `helix-canvas-node` and `helix-canvas-edge`\nelements, so they are in the served markup whichever renderer wrote them. The\nlibrary fetches nothing, and an array passed to an element is missing from\nthe first paint of a server-rendered React page. `fromJsonCanvas` turns a\nJSON Canvas document into their props, and `toJsonCanvas()` writes a board\nback out.",
+          "description": "A board of cards and connectors, drawn by Helix. On a canvas every position\nis data that someone placed, so drawing is arithmetic over rectangles with no\nlayout to compute. `Map` takes a slotted map, because another renderer draws\nits tiles.\n\nThe format is [JSON Canvas](https://jsoncanvas.org), an open format. Each\nnode has an `x`, `y`, `width`, `height`, and a type. Each edge names the two\nnodes it joins and the sides it leaves and arrives on. A card belongs to a\ngroup when it sits inside the group's bounds.\n\nThe cards are text in the DOM, so a screen reader can read them. The family\nadds a reading order and states each card's connections as text. `order` sets\nthe reading order:\n- `spatial` bands the cards into rows.\n- `edges` follows the arrows, starting from the cards that nothing points to.\n\n**Cards move by default.** The board writes the new `x` and `y` onto the\ncard, the way an input writes its own value, and dispatches two events:\n- `helix-before-move` for every step. Cancel it to hold the positions in your\n  own state and apply them yourself.\n- `helix-move` once the move is finished.\n\nA resize dispatches the same pair with a size. Set `readonly` on the board to\nkeep every card in place, such as on a published board. Set `readonly` on one\ncard or connection to keep only that one in place.\n\nSet `snap` to a length in the document's units, such as `32`, and a card\nthat is moved or resized lands on a multiple of it. Carrying a card, a\ncorner, a connection, or the selection box near the edge of the board moves\nthe board under it, so a card can be taken to a place off screen in one\ndrag. A connection let go within 20 pixels of a card arrives at it. A\ndouble click on the empty board zooms in about that point, and Shift with a\ndouble click zooms out.\n\nKeyboard behavior:\n- One card holds the board's tab stop.\n- The arrow keys move through the cards in reading order. The card you land\n  on scrolls into view, and its connections are announced with it.\n- The card you land on is selected. Control or Command with an arrow key,\n  Home, or End moves without changing the selection, and Space adds the card\n  to the selection or takes it out, so you can select cards that are not\n  next to each other.\n- Shift with an arrow key moves the card: by 16 units, or to the next\n  multiple of `snap` where it is set. Alt with an arrow key resizes it from\n  its bottom right corner the same way.\n- The connections leaving a card are stops of their own, straight after it.\n  Enter on one moves to the card it arrives at.\n- What a key changes that a reader cannot see is said: where a card moved\n  to, its new size, how many cards are selected, and the zoom. A selected\n  card or connection says so when a reader arrives on it.\n- Control or Command with C copies the selected cards, and the connections\n  between them, as a JSON Canvas document in text, which another board or\n  an app that reads the format takes. A paste is your page's: listen for\n  `paste` on the board, read the text with `fromJsonCanvas`, and add the\n  cards it holds.\n- Control or Command with Z undoes the last move or resize the board made,\n  and with Shift, or Control with Y, makes it again. `undo()` and `redo()`\n  do the same from a script. Each asks with `helix-before-move` and tells\n  with `helix-move`, as a move does, so a board that holds its positions in\n  your state is undone through your state.\n\nEvery drag also works with clicks, as WCAG 2.5.7 requires for a pointer that\ncannot hold a button down. Click a selected card's move handle, a corner, a\ncard's connection point, or the end of a selected connection to pick it up.\nIt follows the pointer with no button held, and the next click puts it down\nwhere a drag would have. On touch, the next tap sets where it lands. Escape,\nor a press outside the board, puts it back. So a finger connects two cards\nwith three taps: the card, one of its points, and the card to connect to.\n\nConnecting and removing dispatch requests, and your code applies them:\n- Drawing from a card's handle to another card, or pressing C on one card and\n  Enter on another, dispatches `helix-connect`.\n- Delete on a card or a connection dispatches `helix-remove`. The event names\n  every connection that removing the card would leave without an end.\n\nOnce your page removes what Delete asked for, focus moves to the next stop,\nto the one before where it was the last, and to the board where none is\nleft. A focused card your page removes for its own reasons hands focus on\nthe same way, unless the reader has already moved focus somewhere else.\n\nThe board applies a move itself, because the card already exists. A\nconnection is a new element, and React discards an element the board adds to\nits markup on the next render, so you write the connection.\n\n**`edgeRoute` draws the connections' lines your own way**: a function from\nwhere a line leaves and arrives, and the sides it does, to its SVG path, for\na route such as one that bends around the cards between. What it returns\nis the line drawn, the line pressed and focused, and the one an arrowhead\nsits at the end of. Nothing back draws the board's own.\n\nAdd `minimap` to `controls` for a picture of the whole board in a corner:\neach card as a box, and a frame around what is on screen. A press or a drag\non it brings that place to the middle of the view. It is for a pointer, and\na screen reader skips it: the arrow keys and `show()` reach every card.\n\nCards and connections are `helix-canvas-node` and `helix-canvas-edge`\nelements, so they are in the served markup whichever renderer wrote them. The\nlibrary fetches nothing, and an array passed to an element is missing from\nthe first paint of a server-rendered React page. `fromJsonCanvas` turns a\nJSON Canvas document into their props, and `toJsonCanvas()` writes a board\nback out.",
           "name": "HelixHeadlessCanvas",
           "cssProperties": [
             {
@@ -15707,6 +15723,18 @@
               "description": "The box a Shift-drag across the empty board draws, which selects the cards it touches.",
               "name": "marquee"
             },
+            {
+              "description": "The picture of the whole board, under `controls=\"minimap\"`.",
+              "name": "minimap"
+            },
+            {
+              "description": "One card in the minimap.",
+              "name": "minimap-node"
+            },
+            {
+              "description": "The frame in the minimap around what is on screen.",
+              "name": "minimap-view"
+            },
             {
               "description": "The button that moves the board down.",
               "name": "pan-down"
@@ -15919,6 +15947,14 @@
                 "words": true
               }
             },
+            {
+              "kind": "field",
+              "name": "edgeRoute",
+              "type": {
+                "text": "CanvasRoute | undefined"
+              },
+              "description": "Draws every connection's line: a function from where it leaves and\narrives, and the sides it does, to its SVG path and where its label sits.\n\nAbsent, or returning nothing for a connection, draws the board's own\nroute. A function that throws draws the board's own too, and the error is\nreported to the page as an uncaught one. Set it as a property."
+            },
             {
               "kind": "field",
               "name": "fallbackLabel",
@@ -17118,6 +17154,49 @@
               ],
               "description": "The line a connection is drawn along on the plane, and its middle, where\nboth its cards are on the board; nothing where either is not."
             },
+            {
+              "kind": "method",
+              "name": "draw",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "{ d: string; mid: { x: number; y: number } }"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "edge",
+                  "type": {
+                    "text": "CanvasEdge"
+                  }
+                },
+                {
+                  "name": "from",
+                  "type": {
+                    "text": "CanvasNode"
+                  }
+                },
+                {
+                  "name": "to",
+                  "type": {
+                    "text": "CanvasNode"
+                  }
+                },
+                {
+                  "name": "path",
+                  "type": {
+                    "text": "CanvasPath"
+                  }
+                },
+                {
+                  "name": "drawnHeads",
+                  "type": {
+                    "text": "{ start: boolean; end: boolean }"
+                  }
+                }
+              ],
+              "description": "One connection's line, by `edgeRoute` where it draws one, and by the board's own where not."
+            },
             {
               "kind": "method",
               "name": "cardOf",
@@ -18411,6 +18490,44 @@
               ],
               "description": "The connection being made, drawn from where it starts to the pointer, or to\nthe card a keyboard reader is on."
             },
+            {
+              "kind": "field",
+              "name": "onScreen",
+              "type": {
+                "text": "{ x: number; y: number; width: number; height: number }"
+              },
+              "privacy": "private",
+              "description": "The part of the document on screen, in its own units.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "minimapArea",
+              "type": {
+                "text": "{ x: number; y: number; width: number; height: number }"
+              },
+              "privacy": "private",
+              "description": "What the minimap shows: every card and what is on screen, with room around them.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "handleMinimapPointer",
+              "privacy": "private",
+              "readonly": true,
+              "description": "A press or a drag on the minimap, which brings the place under it to the\nmiddle of the view.\n\n**The point is read through the picture's own scale**: the area is drawn\nwhole and centered in the box, so the box's spare width or height is split\neither side of it."
+            },
+            {
+              "kind": "method",
+              "name": "renderMinimap",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "TemplateResult | typeof nothing"
+                }
+              },
+              "description": "The minimap, under `controls=\"minimap\"`: each card as a box, and a frame\naround what is on screen.\n\n**A picture for a pointer**, hidden from screen readers and taking no\nfocus, as a map's own overview is: the arrow keys and `show()` already take\na keyboard to any card, and a second way that says nothing a reader can\nuse would be a stop that does nothing."
+            },
             {
               "kind": "field",
               "name": "controls",
@@ -20095,6 +20212,22 @@
             "module": "./canvas-document.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "CanvasRoute",
+          "declaration": {
+            "name": "CanvasRoute",
+            "module": "./canvas-document.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "CanvasRouteEnds",
+          "declaration": {
+            "name": "CanvasRouteEnds",
+            "module": "./canvas-document.js"
+          }
+        },
         {
           "kind": "js",
           "name": "CanvasSide",
@@ -25806,7 +25939,35 @@
                   }
                 }
               ],
-              "description": "Moves focus to turn `at`, drawing it first where the transcript is\nwindowed and it is not drawn.\n\n**A turn takes focus only once a reader moves to it**, so the\n`tabindex=\"-1\"` a turn written as a child needs is written then, long\nafter any server's markup has hydrated, and never on a turn nobody moved\nto."
+              "description": "Moves focus to turn `at`, drawing it first where the transcript is\nwindowed and it is not drawn.\n\n**A turn takes focus only once a reader moves to it**, so the `tabindex`\nit needs is written then, long after any server's markup has hydrated,\nand never on a turn nobody moved to."
+            },
+            {
+              "kind": "field",
+              "name": "stop",
+              "type": {
+                "text": "HTMLElement | undefined"
+              },
+              "privacy": "private",
+              "description": "The turn that is a tab stop because a reader moved to it."
+            },
+            {
+              "kind": "method",
+              "name": "visit",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "turn",
+                  "type": {
+                    "text": "HTMLElement"
+                  }
+                }
+              ],
+              "description": "Focuses a turn, making it the transcript's one stop a reader moved to.\n\n**`0`, and never `-1`.** Chromium leaves the whole of a shadow host at a\nnegative `tabindex` out of the Tab order, its own controls and what is\nslotted into it alike, so a turn at `-1` lost its links and its Try again\nonce a reader had paged through it. The stop moves with the reader, and a\n`tabindex` you wrote on a turn is left as it is."
             },
             {
               "kind": "method",
@@ -101285,7 +101446,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Wraps a map drawn by MapLibre, Leaflet, or another renderer. The frame adds\na name for the map, a column of controls, and a strip for the map credit.\nHelix does not draw the map itself.\n\nThe controls are one column, and `controls` names which ones: `fullscreen`,\n`layers`, `tilt`, `zoom`, and `compass`, top to bottom. `zoom compass\nfullscreen` by default. The compass's needle points north as the map turns,\nand pressing it turns the map to face north.\n\nAdd `pan` and `rotate` for buttons around the compass that move and turn the\nmap. Dragging is otherwise the only way a pointer moves the map, so add them\nwhere the map has to be usable without dragging, as WCAG 2.2 asks at level\nAA. The arrow keys pan the map and Shift with Left or Right turns it either\nway.\n\nThe pan and zoom buttons and the arrow keys send `helix-map-pan` and\n`helix-map-zoom`. Move your map in response, or connect it with\n`connectMap` from `@fusion.dev/helix-map`, which does this for you.\n\nAdd `tilt` to `controls` for the 3D button, which a map with 3D buildings\nor terrain needs. It is a toggle. Pressed, it tilts the map 50 degrees, and\n`connectMap` raises the buildings and the ground. Pressed again, it makes the\nmap flat, and lays them flat too. Shift with Up or Down tilts the map in\nsteps. Turning and tilting send `helix-map-rotate` and `helix-map-tilt`,\nwhich `connectMap` answers on MapLibre. Leaflet draws maps flat and does not\nrotate.\n\nAdd `layers` to `controls` for a layers button. It opens a menu with a tile\nfor each layer, which sets the layer's `hidden` attribute. Layers with the\nsame `group`, such as a route and its dotted legs, share one tile. A tile\nsends `helix-before-toggle` from the layer first, so you can store the\nchoice or refuse it, and `helix-toggle` from it once `hidden` holds the\nchoice.\n\nImagery, a `helix-map-raster` with `ground`, is a map type and not a tile.\nThe menu opens with a card for each type, Standard, Hybrid, and Satellite,\nwith a picture of the map in it, and `map-type` says which is chosen.\nStandard hides the imagery, Hybrid draws it under the roads and names, and\nSatellite draws it alone. Choosing one sends `helix-before-change` with its\nname, and `change` once `map-type` holds it. `connectMap` does not draw a\nhidden layer, so a layer you write with `hidden` starts turned off.\n\nMarkers, routes, areas, live positions, and points layers go inside the\nframe as child elements.",
+          "description": "Wraps a map drawn by MapLibre, Leaflet, or another renderer. The frame adds\na name for the map, a column of controls, and a strip for the map credit.\nHelix does not draw the map itself.\n\nThe controls are one column, and `controls` names which ones: `fullscreen`,\n`layers`, `tilt`, `zoom`, and `compass`, top to bottom. `zoom compass\nfullscreen` by default. The compass's needle points north as the map turns,\nand pressing it turns the map to face north.\n\nAdd `pan` and `rotate` for buttons around the compass that move and turn the\nmap. Dragging is otherwise the only way a pointer moves the map, so add them\nwhere the map has to be usable without dragging, as WCAG 2.2 asks at level\nAA. The arrow keys pan the map and Shift with Left or Right turns it either\nway.\n\nThe pan and zoom buttons and the arrow keys send `helix-map-pan` and\n`helix-map-zoom`. Move your map in response, or connect it with\n`connectMap` from `@fusion.dev/helix-map`, which does this for you.\n\nAdd `tilt` to `controls` for the 3D button, which a map with 3D buildings\nor terrain needs. It is a toggle. Pressed, it tilts the map 50 degrees, and\n`connectMap` raises the buildings and the ground. Pressed again, it makes the\nmap flat, and lays them flat too. Shift with Up or Down tilts the map in\nsteps. Turning and tilting send `helix-map-rotate` and `helix-map-tilt`,\nwhich `connectMap` answers on MapLibre. Leaflet draws maps flat and does not\nrotate.\n\nAdd `layers` to `controls` for a layers button. It opens a menu with a tile\nfor each layer, which sets the layer's `hidden` attribute. Layers with the\nsame `group`, such as a route and its dotted legs, share one tile. A tile\nsends `helix-before-toggle` from the layer first, so you can store the\nchoice or refuse it, and `helix-toggle` from it once `hidden` holds the\nchoice. Escape closes the menu and returns focus to its button, and the menu\ncloses when focus moves on from it or a press lands outside the map.\n\nImagery, a `helix-map-raster` with `ground`, is a map type and not a tile.\nThe menu opens with a card for each type, Standard, Hybrid, and Satellite,\nwith a picture of the map in it, and `map-type` says which is chosen.\nStandard hides the imagery, Hybrid draws it under the roads and names, and\nSatellite draws it alone. Choosing one sends `helix-before-change` with its\nname, and `change` once `map-type` holds it. `connectMap` does not draw a\nhidden layer, so a layer you write with `hidden` starts turned off.\n\nMarkers, routes, areas, live positions, and points layers go inside the\nframe as child elements.",
           "name": "HelixHeadlessMap",
           "cssProperties": [
             {
@@ -102068,6 +102229,13 @@
               "readonly": true,
               "description": "Closes the layers menu on a press anywhere outside the frame."
             },
+            {
+              "kind": "field",
+              "name": "handleMenuFocusOut",
+              "privacy": "private",
+              "readonly": true,
+              "description": "Closes the layers menu when focus moves on from its button and the menu,\nas a Tab past the last tile does. Focus leaving the page, with nothing\nfocused in its place, leaves the menu as it is."
+            },
             {
               "kind": "field",
               "name": "handleMenuKeydown",
@@ -106768,7 +106936,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "One element covers three kinds of row, and what you give it decides which:\n- Content in the `submenu` slot makes the row open a submenu page.\n- `checked` makes the row a choice.\n- With neither, the row is a command.\n\nThe role follows the kind. A row with `checked` is `menuitemcheckbox` with\n`aria-checked`, and `exclusive` makes it `menuitemradio`, for a set where\nonly one can be on. A row that opens a page keeps `menuitem` and sets\n`aria-haspopup`.\n\nChoosing a choice row checks or unchecks it before `helix-select` is sent,\nso a listener reads the new `checked`. An `exclusive` row turns on and turns\noff the `exclusive` rows next to it. Cancel `helix-before-toggle` to keep a\nrow as it is and set `checked` yourself.\n\nThe menu sets whether the row's page is showing as a property, never as an\nattribute. An attribute written onto your element after it upgrades causes a\nhydration mismatch.\n\n`shortcut` shows a row's keyboard shortcut after its label, drawn by `Kbd`\nin the platform's glyphs, and gives the row `aria-keyshortcuts`. It binds\nnothing: the shortcut is the page's to bind. Other trailing words, such as a\ncount, go in the `end` slot.\n\nThe row is named by its label alone. Words in `description`, a line under the\nlabel, and in `end` describe it instead, through `aria-describedby`, as\nReact Aria's menu item does with its description: a reader hears \"Copy\",\nthen \"Copies the selection\".\n\nA development build warns when a row has no words to be named by, such as a\nrow holding only an icon with no label.\n\nThe check mark and the caret are the fallbacks of the `check` and `chevron`\nslots, so a mark of your own replaces either by being slotted. Neither is\nread as part of the row's name.",
+          "description": "One element covers three kinds of row, and what you give it decides which:\n- Content in the `submenu` slot makes the row open a submenu page.\n- `checked` makes the row a choice.\n- With neither, the row is a command.\n\nThe role follows the kind. A row with `checkable` or `checked` is\n`menuitemcheckbox` with `aria-checked`, and an `exclusive` row is\n`menuitemradio`, for a set where only one can be on. A row that opens a page\nkeeps `menuitem` and sets `aria-haspopup`.\n\nChoosing a choice row checks or unchecks it before `helix-select` is sent,\nso a listener reads the new `checked`. An `exclusive` row turns on and turns\noff the `exclusive` rows next to it. Cancel `helix-before-toggle` to keep a\nrow as it is and set `checked` yourself.\n\nSpace on a choice row changes it and leaves the menu open, so a reader can\nset several in a row, as the APG's menu does. Enter and a press change it and\nclose the menu. `close-on-select=\"false\"` on the row keeps the menu open after\nany choice of it, and `close-on-select` on the row closes it after a Space as\nwell.\n\nThe menu sets whether the row's page is showing as a property, never as an\nattribute. An attribute written onto your element after it upgrades causes a\nhydration mismatch.\n\n`shortcut` shows a row's keyboard shortcut after its label, drawn by `Kbd`\nin the platform's glyphs, and gives the row `aria-keyshortcuts`. It binds\nnothing: the shortcut is the page's to bind. Other trailing words, such as a\ncount, go in the `end` slot.\n\nThe row is named by its label alone. Words in `description`, a line under the\nlabel, and in `end` describe it instead, through `aria-describedby`, as\nReact Aria's menu item does with its description: a reader hears \"Copy\",\nthen \"Copies the selection\".\n\nA development build warns when a row has no words to be named by, such as a\nrow holding only an icon with no label.\n\nThe check mark and the caret are the fallbacks of the `check` and `chevron`\nslots, so a mark of your own replaces either by being slotted. Neither is\nread as part of the row's name.",
           "name": "HelixHeadlessMenuItem",
           "cssParts": [
             {
@@ -106846,7 +107014,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Whether the row is one of a set of choices.\n\nSeparate from `checked`, and it has to be. A row that is off is still a\nchoice, and `checked` alone cannot say so: an unticked row and a row that\nwas never tickable look identical from here. Announcing only the ticked one\nas a checkbox tells a reader its siblings are commands, which is the one\nthing they are not.\n\n`checked` implies it, so a row that is on never has to say both.\n\nChoosing the row checks or unchecks it, after a `helix-before-toggle` that\nyou can cancel.",
+              "description": "Whether the row is one of a set of choices.\n\nSeparate from `checked`, and it has to be. A row that is off is still a\nchoice, and `checked` alone cannot say so: an unticked row and a row that\nwas never tickable look identical from here. Announcing only the ticked one\nas a checkbox tells a reader its siblings are commands, which is the one\nthing they are not.\n\n`checked` and `exclusive` imply it, so a row that is on, or one of a set,\nnever has to say both.\n\nChoosing the row checks or unchecks it, after a `helix-before-toggle` that\nyou can cancel.",
               "attribute": "checkable",
               "reflects": true
             },
@@ -106860,6 +107028,15 @@
               "description": "Whether the row is checked.\n\nThe row changes it when it is chosen. Not reflected: the attribute is the\nstate you start the row in, and `:state(checked)` carries the current one.",
               "attribute": "checked"
             },
+            {
+              "kind": "field",
+              "name": "closeOnSelect",
+              "type": {
+                "text": "boolean | undefined"
+              },
+              "description": "Whether choosing the row closes the menu.\n\nUnset takes the menu's `close-on-select`, which is on, and keeps the menu\nopen after a Space on a choice row. Write `close-on-select=\"false\"` for a\nrow that changes something the reader is watching, such as a zoom step.",
+              "attribute": "close-on-select"
+            },
             {
               "kind": "field",
               "name": "disabled",
@@ -106888,7 +107065,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Whether only one row in its set can be checked at a time.\n\nThe set is the run of `exclusive` rows next to this one, up to the first\nelement that is not one, such as a divider. Choosing a row in it checks\nthat row and unchecks the others. Choosing the row that is checked leaves\nit checked. `menuitemradio` tells a reader which kind of set they are in,\nwhere `menuitemcheckbox` says every row is independent.\n\nMeaningless without `checkable`, since a row that cannot be ticked is not\none of a set of anything.",
+              "description": "Whether only one row in its set can be checked at a time.\n\nThe set is the run of `exclusive` rows next to this one, up to the first\nelement that is not one, such as a divider. Choosing a row in it checks\nthat row and unchecks the others. Choosing the row that is checked leaves\nit checked. `menuitemradio` tells a reader which kind of set they are in,\nwhere `menuitemcheckbox` says every row is independent.\n\nIt makes the row a choice, so it needs no `checkable` beside it.",
               "attribute": "exclusive",
               "reflects": true
             },
@@ -107146,7 +107323,14 @@
                 "type": {
                   "text": "void"
                 }
-              }
+              },
+              "parameters": [
+                {
+                  "name": "space",
+                  "default": "false"
+                }
+              ],
+              "description": "Chooses the row. `space` is whether a Space chose it, which keeps the menu\nopen on a choice row unless the row says otherwise."
             },
             {
               "kind": "field",
@@ -107154,6 +107338,16 @@
               "privacy": "private",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "spacePressed",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether the click on its way is the one a Space on a linked row sent."
+            },
             {
               "kind": "field",
               "name": "handleKeydown",
@@ -107545,7 +107739,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Whether the row is one of a set of choices.\n\nSeparate from `checked`, and it has to be. A row that is off is still a\nchoice, and `checked` alone cannot say so: an unticked row and a row that\nwas never tickable look identical from here. Announcing only the ticked one\nas a checkbox tells a reader its siblings are commands, which is the one\nthing they are not.\n\n`checked` implies it, so a row that is on never has to say both.\n\nChoosing the row checks or unchecks it, after a `helix-before-toggle` that\nyou can cancel.",
+              "description": "Whether the row is one of a set of choices.\n\nSeparate from `checked`, and it has to be. A row that is off is still a\nchoice, and `checked` alone cannot say so: an unticked row and a row that\nwas never tickable look identical from here. Announcing only the ticked one\nas a checkbox tells a reader its siblings are commands, which is the one\nthing they are not.\n\n`checked` and `exclusive` imply it, so a row that is on, or one of a set,\nnever has to say both.\n\nChoosing the row checks or unchecks it, after a `helix-before-toggle` that\nyou can cancel.",
               "fieldName": "checkable"
             },
             {
@@ -107557,6 +107751,14 @@
               "description": "Whether the row is checked.\n\nThe row changes it when it is chosen. Not reflected: the attribute is the\nstate you start the row in, and `:state(checked)` carries the current one.",
               "fieldName": "checked"
             },
+            {
+              "name": "close-on-select",
+              "type": {
+                "text": "boolean | undefined"
+              },
+              "description": "Whether choosing the row closes the menu.\n\nUnset takes the menu's `close-on-select`, which is on, and keeps the menu\nopen after a Space on a choice row. Write `close-on-select=\"false\"` for a\nrow that changes something the reader is watching, such as a zoom step.",
+              "fieldName": "closeOnSelect"
+            },
             {
               "name": "disabled",
               "type": {
@@ -107581,7 +107783,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Whether only one row in its set can be checked at a time.\n\nThe set is the run of `exclusive` rows next to this one, up to the first\nelement that is not one, such as a divider. Choosing a row in it checks\nthat row and unchecks the others. Choosing the row that is checked leaves\nit checked. `menuitemradio` tells a reader which kind of set they are in,\nwhere `menuitemcheckbox` says every row is independent.\n\nMeaningless without `checkable`, since a row that cannot be ticked is not\none of a set of anything.",
+              "description": "Whether only one row in its set can be checked at a time.\n\nThe set is the run of `exclusive` rows next to this one, up to the first\nelement that is not one, such as a divider. Choosing a row in it checks\nthat row and unchecks the others. Choosing the row that is checked leaves\nit checked. `menuitemradio` tells a reader which kind of set they are in,\nwhere `menuitemcheckbox` says every row is independent.\n\nIt makes the row a choice, so it needs no `checkable` beside it.",
               "fieldName": "exclusive"
             },
             {
@@ -107703,7 +107905,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "The trigger is slotted and stays your own element, as with the tooltip. The\nmenu renders its surface in the top layer with the popover API, so an\nancestor with `overflow: hidden` does not clip it and it needs no `z-index`.\n\nSlot a `helix-button` or `helix-icon-button` as the trigger, and the menu\ntells it that it opens a menu and whether the menu is open, inside its own\nshadow root. On a plain element, such as a `<button>`, the menu writes\n`aria-haspopup=\"menu\"` and `aria-expanded`, from a frame after its own first\nrender, so a server's markup is never changed while a framework hydrates it.\nIt never writes `aria-expanded` where you wrote it yourself.\n\nSubmenus drill down by default. A submenu replaces the panel's content, and a\nback row returns to the previous page. One panel stays inside a narrow\nwindow, and works on touch screens, which have no hover.\n\n**`submenus=\"flyout\"` opens each submenu in a panel of its own beside its\nrow**, as React Aria's `SubmenuTrigger` and Radix's `Sub` do. Resting the\npointer on the row opens it, and a pointer crossing toward the open panel\nover the rows between keeps it open, as Radix's grace area does. Right Arrow\nopens a row's submenu on its first row, and Left Arrow or Escape closes it\nand returns focus to the row, the two arrows swapping on a right-to-left\npage. The row says `aria-expanded`, and the panel is a `menu` named by the\nrow.\n\nThe root holds which page is open, because only one page shows at a time. It\nsets this on items as a property, never as an attribute. An attribute written\nonto your element after it upgrades causes a hydration mismatch.\n\nGroup rows under a heading with `Menu.Section`, which is a `group` named by\nits heading. Between runs of rows, a `<helix-divider>` is a separator a\nscreen reader announces.\n\nKeys: Enter, Space or Down Arrow on the trigger opens the menu on its first\nrow, and Up Arrow on its last. In the menu, Up and Down Arrow move between\nrows, Home and End go to the first and the last, a typed letter moves to\nthe next row whose name starts with it, Enter and Space choose, Right Arrow\nopens a row's submenu and Left Arrow goes back, the two swapping on a\nright-to-left page. Left Arrow on the top page does nothing. Escape closes\nthe menu and returns focus to the trigger. Tab closes it and moves on.\n\nWhile it is open, the surface carries the trigger's width as\n`--floating-anchor-inline-size` and the room left below it as\n`--floating-available-block-size`, as Radix's dropdown menu publishes its\ntrigger's width, for a menu as wide as its trigger:\n`helix-menu::part(surface) { min-inline-size: var(--floating-anchor-inline-size) }`.\n\nWith `context`, the trigger is an area and the menu is its context menu: a\nright-click, a long press, Shift+F10 or the menu key over the area opens it\nat the pointer, or at the area's corner from the keyboard, as Radix's context\nmenu does. A press on the area does not open it, and closing it returns focus\nto where it was. A touch or a pen held still on the area opens it too, on\nevery browser, since iOS sends no `contextmenu` for one.\n\n**A trigger with its own action.** With `open-on=\"long-press\"`, a press on\nthe trigger is the trigger's own, and a press held for half a second opens\nthe menu, as React Aria's `trigger=\"longPress\"` does. Alt+Down or Alt+Up\nopens it from the keyboard, and the trigger is described by\n`long-press-label`, which says so.",
+          "description": "The trigger is slotted and stays your own element, as with the tooltip. The\nmenu renders its surface in the top layer with the popover API, so an\nancestor with `overflow: hidden` does not clip it and it needs no `z-index`.\n\nSlot a `helix-button` or `helix-icon-button` as the trigger, and the menu\ntells it that it opens a menu and whether the menu is open, inside its own\nshadow root. On a plain element, such as a `<button>`, the menu writes\n`aria-haspopup=\"menu\"` and `aria-expanded`, from a frame after its own first\nrender, so a server's markup is never changed while a framework hydrates it.\nIt never writes `aria-expanded` where you wrote it yourself.\n\nSubmenus drill down by default. A submenu replaces the panel's content, and a\nback row returns to the previous page. One panel stays inside a narrow\nwindow, and works on touch screens, which have no hover.\n\n**`submenus=\"flyout\"` opens each submenu in a panel of its own beside its\nrow**, as React Aria's `SubmenuTrigger` and Radix's `Sub` do. Resting the\npointer on the row opens it, and a pointer crossing toward the open panel\nover the rows between keeps it open, as Radix's grace area does. Right Arrow\nopens a row's submenu on its first row, and Left Arrow or Escape closes it\nand returns focus to the row, the two arrows swapping on a right-to-left\npage. The row says `aria-expanded`, and the panel is a `menu` named by the\nrow.\n\nThe root holds which page is open, because only one page shows at a time. It\nsets this on items as a property, never as an attribute. An attribute written\nonto your element after it upgrades causes a hydration mismatch.\n\nGroup rows under a heading with `Menu.Section`, which is a `group` named by\nits heading. Between runs of rows, a `<helix-divider>` is a separator a\nscreen reader announces.\n\nKeys: Enter, Space or Down Arrow on the trigger opens the menu on its first\nrow, and Up Arrow on its last. In the menu, Up and Down Arrow move between\nrows, Home and End go to the first and the last, a typed letter moves to\nthe next row whose name starts with it, Enter and Space choose (Space on a\nchoice row changes it and leaves the menu open), Right Arrow\nopens a row's submenu and Left Arrow goes back, the two swapping on a\nright-to-left page. Left Arrow on the top page does nothing. Escape closes\nthe menu and returns focus to the trigger. Tab closes it and moves on.\n\nWhile it is open, the surface carries the trigger's width as\n`--floating-anchor-inline-size` and the room left below it as\n`--floating-available-block-size`, as Radix's dropdown menu publishes its\ntrigger's width, for a menu as wide as its trigger:\n`helix-menu::part(surface) { min-inline-size: var(--floating-anchor-inline-size) }`.\n\nWith `context`, the trigger is an area and the menu is its context menu: a\nright-click, a long press, Shift+F10 or the menu key over the area opens it\nat the pointer, or at the area's corner from the keyboard, as Radix's context\nmenu does. A press on the area does not open it, and closing it returns focus\nto where it was. A touch or a pen held still on the area opens it too, on\nevery browser, since iOS sends no `contextmenu` for one.\n\n**A trigger with its own action.** With `open-on=\"long-press\"`, a press on\nthe trigger is the trigger's own, and a press held for half a second opens\nthe menu, as React Aria's `trigger=\"longPress\"` does. Alt+Down or Alt+Up\nopens it from the keyboard, and the trigger is described by\n`long-press-label`, which says so.",
           "name": "HelixHeadlessMenu",
           "cssProperties": [
             {
@@ -107787,6 +107989,16 @@
                 "words": true
               }
             },
+            {
+              "kind": "field",
+              "name": "closeOnSelect",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "true",
+              "description": "Whether choosing a row closes the menu.\n\nOn by default, and a Space on a choice row leaves the menu open either way.\nWrite `close-on-select=\"false\"` to keep the menu open after every choice, as\nArk UI's `closeOnSelect` does. A row's own `close-on-select` wins over this.",
+              "attribute": "close-on-select"
+            },
             {
               "kind": "field",
               "name": "context",
@@ -109146,6 +109358,15 @@
               "description": "The text of the row that returns from a submenu.",
               "fieldName": "backLabel"
             },
+            {
+              "name": "close-on-select",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "true",
+              "description": "Whether choosing a row closes the menu.\n\nOn by default, and a Space on a choice row leaves the menu open either way.\nWrite `close-on-select=\"false\"` to keep the menu open after every choice, as\nArk UI's `closeOnSelect` does. A row's own `close-on-select` wins over this.",
+              "fieldName": "closeOnSelect"
+            },
             {
               "name": "context",
               "type": {
@@ -149963,7 +150184,7 @@
                 "text": "number"
               },
               "privacy": "private",
-              "description": "The index of the stage the reader is on, or `-1`.",
+              "description": "The index of the stage the reader is on, or `-1`.\n\nRead from `active` once anything has set it, because a move writes\n`active` at once and each step's `current` only on the next update: two\ncalls to `next()` in one task then move two stages.",
               "readonly": true
             },
             {
@@ -192420,6 +192641,6 @@
   ],
   "helix": {
     "package": "@fusion.dev/helix-headless",
-    "version": "0.162.1"
+    "version": "0.163.0"
   }
 }

package/dist/canvas/index.d.ts

@@ -1,4 +1,4 @@
 export { HelixHeadlessCanvasEdge } from './edge/canvas-edge.js';
 export { HelixHeadlessCanvasNode } from './node/canvas-node.js';
-export type { CanvasDocument, CanvasEdge, CanvasEdgeProps, CanvasEnd, CanvasNode, CanvasNodeProps, CanvasPath, CanvasSide, CanvasTone, } from './root/canvas-root.js';
+export type { CanvasDocument, CanvasEdge, CanvasEdgeProps, CanvasEnd, CanvasNode, CanvasNodeProps, CanvasPath, CanvasRoute, CanvasRouteEnds, CanvasSide, CanvasTone, } from './root/canvas-root.js';
 export { fromJsonCanvas, HelixHeadlessCanvas } from './root/canvas-root.js';

package/dist/canvas/root/canvas-document.d.ts

@@ -91,6 +91,39 @@ export declare const port: (node: CanvasNode, side: CanvasSide) => {
 };
 /** How a connector travels between the two cards it joins. */
 export type CanvasPath = 'curve' | 'straight' | 'step';
+/** What a board's `edgeRoute` is given for one connection, in the board's own units. */
+export interface CanvasRouteEnds {
+    /** The connection. */
+    edge: CanvasEdge;
+    /** Where it arrives, on the side of the card it arrives at. */
+    end: {
+        x: number;
+        y: number;
+    };
+    /** The side of the card it leaves. */
+    fromSide: CanvasSide;
+    /** The route the board would draw: the connection's `path`, or the board's. */
+    path: CanvasPath;
+    /** Where it leaves, on the side of the card it leaves. */
+    start: {
+        x: number;
+        y: number;
+    };
+    /** The side of the card it arrives at. */
+    toSide: CanvasSide;
+}
+/**
+ * Draws a connection's line: its SVG path from `start` to `end`, and where its
+ * label sits, the middle of the two ends where it says nothing. Nothing back
+ * draws the board's own.
+ */
+export type CanvasRoute = (ends: CanvasRouteEnds) => {
+    d: string;
+    mid?: {
+        x: number;
+        y: number;
+    } | undefined;
+} | undefined;
 /** A point in the document's own units. */
 type Point = {
     x: number;

package/dist/canvas/root/canvas-root.d.ts

@@ -1,7 +1,7 @@
 import { type CanvasView, HelixElement, type ViewportPanDetail, type ViewportWay, type ViewportZoomDetail } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
-import { type CanvasDocument, type CanvasTone } from './canvas-document.js';
-export type { CanvasDocument, CanvasEdge, CanvasEdgeProps, CanvasEnd, CanvasNode, CanvasNodeProps, CanvasPath, CanvasSide, CanvasTone, } from './canvas-document.js';
+import { type CanvasDocument, type CanvasRoute, type CanvasTone } from './canvas-document.js';
+export type { CanvasDocument, CanvasEdge, CanvasEdgeProps, CanvasEnd, CanvasNode, CanvasNodeProps, CanvasPath, CanvasRoute, CanvasRouteEnds, CanvasSide, CanvasTone, } from './canvas-document.js';
 export { fromJsonCanvas } from './canvas-document.js';
 declare const HelixHeadlessCanvas_base: (new (...args: any[]) => import("@fusion.dev/helix-core").ViewportElement) & typeof HelixElement;
 /**
@@ -92,6 +92,17 @@ declare const HelixHeadlessCanvas_base: (new (...args: any[]) => import("@fusion
  * connection is a new element, and React discards an element the board adds to
  * its markup on the next render, so you write the connection.
  *
+ * **`edgeRoute` draws the connections' lines your own way**: a function from
+ * where a line leaves and arrives, and the sides it does, to its SVG path, for
+ * a route such as one that bends around the cards between. What it returns
+ * is the line drawn, the line pressed and focused, and the one an arrowhead
+ * sits at the end of. Nothing back draws the board's own.
+ *
+ * Add `minimap` to `controls` for a picture of the whole board in a corner:
+ * each card as a box, and a frame around what is on screen. A press or a drag
+ * on it brings that place to the middle of the view. It is for a pointer, and
+ * a screen reader skips it: the arrow keys and `show()` reach every card.
+ *
  * Cards and connections are `helix-canvas-node` and `helix-canvas-edge`
  * elements, so they are in the served markup whichever renderer wrote them. The
  * library fetches nothing, and an array passed to an element is missing from
@@ -148,6 +159,9 @@ declare const HelixHeadlessCanvas_base: (new (...args: any[]) => import("@fusion
  * @csspart label-editor - The field for editing a connection's label or a group's name, placed over that text.
  * @csspart live - A live region that screen readers announce while a connection is being made.
  * @csspart marquee - The box a Shift-drag across the empty board draws, which selects the cards it touches.
+ * @csspart minimap - The picture of the whole board, under `controls="minimap"`.
+ * @csspart minimap-node - One card in the minimap.
+ * @csspart minimap-view - The frame in the minimap around what is on screen.
  * @csspart pan-down - The button that moves the board down.
  * @csspart pan-end - The button that moves the board toward the end of a line of text: right in English.
  * @csspart pan-start - The button that moves the board toward the start of a line of text: left in English.
@@ -210,6 +224,15 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
     controlsLabel: string;
     /** What screen readers hear after a copy, with `{count}` for the cards copied. */
     copiedLabel: string;
+    /**
+     * Draws every connection's line: a function from where it leaves and
+     * arrives, and the sides it does, to its SVG path and where its label sits.
+     *
+     * Absent, or returning nothing for a connection, draws the board's own
+     * route. A function that throws draws the board's own too, and the error is
+     * reported to the page as an uncaught one. Set it as a property.
+     */
+    edgeRoute?: CanvasRoute;
     /** The board's name where `label` is empty. */
     fallbackLabel: string;
     /**
@@ -702,6 +725,8 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * both its cards are on the board; nothing where either is not.
      */
     private geometryOf;
+    /** One connection's line, by `edgeRoute` where it draws one, and by the board's own where not. */
+    private draw;
     /** The card an event came from, wherever inside it the event began. */
     private cardOf;
     /**
@@ -1244,6 +1269,29 @@ export declare class HelixHeadlessCanvas extends HelixHeadlessCanvas_base {
      * the card a keyboard reader is on.
      */
     private renderDraft;
+    /** The part of the document on screen, in its own units. */
+    private get onScreen();
+    /** What the minimap shows: every card and what is on screen, with room around them. */
+    private get minimapArea();
+    /**
+     * A press or a drag on the minimap, which brings the place under it to the
+     * middle of the view.
+     *
+     * **The point is read through the picture's own scale**: the area is drawn
+     * whole and centered in the box, so the box's spare width or height is split
+     * either side of it.
+     */
+    private readonly handleMinimapPointer;
+    /**
+     * The minimap, under `controls="minimap"`: each card as a box, and a frame
+     * around what is on screen.
+     *
+     * **A picture for a pointer**, hidden from screen readers and taking no
+     * focus, as a map's own overview is: the arrow keys and `show()` already take
+     * a keyboard to any card, and a second way that says nothing a reader can
+     * use would be a stop that does nothing.
+     */
+    private renderMinimap;
     protected render(): TemplateResult;
 }
 declare global {