@fusion.dev/helix-docs 0.176.1 → 0.177.1

package/content/canvases.mdx

@@ -0,0 +1,141 @@
+---
+description: Add a board of cards and connections that people can move, connect, and read with any input, and save it as JSON Canvas.
+section: Essentials
+title: Canvases
+---
+
+# Canvases
+
+Helix Canvas draws a board of cards and the connections between them. People
+pan and zoom the board, move and resize cards, draw connections, and walk the
+board in reading order from the keyboard. The board reads and writes
+[JSON Canvas](https://jsoncanvas.org), an open format.
+
+## Add a board
+
+Write each card as a `helix-canvas-node` and each connection as a
+`helix-canvas-edge`. A card's `x`, `y`, `width`, and `height` are in the
+document's own units, and a connection names its two cards by `name`:
+
+```html
+<helix-canvas label="Launch plan">
+  <helix-canvas-node name="draft" x="0" y="0" width="160" height="64">Draft the email</helix-canvas-node>
+  <helix-canvas-node name="ship" tone="success" x="256" y="0" width="160" height="64">Publish the release</helix-canvas-node>
+  <helix-canvas-edge from="draft" to="ship"></helix-canvas-edge>
+</helix-canvas>
+```
+
+```js
+import '@fusion.dev/helix/canvas'
+```
+
+Give the board a `label` that says what it holds. A screen reader announces it
+as "Launch plan, canvas".
+
+## Load and save a document
+
+`fromJsonCanvas` turns a JSON Canvas document into the props of the elements.
+What a card shows is yours to render, so this example writes each text card's
+text:
+
+```js
+import { fromJsonCanvas } from '@fusion.dev/helix/canvas'
+
+const board = document.querySelector('helix-canvas')
+const { nodes, edges } = fromJsonCanvas(saved)
+for (const node of nodes) {
+  const card = document.createElement('helix-canvas-node')
+  const { group, height, label, name, tone, width, x, y } = node
+  Object.assign(card, { group, height, label, name, tone, width, x, y })
+  card.textContent = node.text ?? ''
+  board.append(card)
+}
+for (const edge of edges) {
+  const line = document.createElement('helix-canvas-edge')
+  const { from, fromSide, label, name, to, toSide, tone } = edge
+  Object.assign(line, { from, fromSide, label, name, to, toSide, tone })
+  board.append(line)
+}
+```
+
+`board.toJsonCanvas()` writes the board back out as a JSON Canvas document.
+
+## Keep the board in your state
+
+The board moves a card itself and sends `helix-move` when the move is finished.
+To keep positions in your own state, cancel `helix-before-move` and write the
+positions from its detail:
+
+```js
+board.addEventListener('helix-before-move', (event) => {
+  event.preventDefault()
+  for (const { name, x, y } of event.detail.nodes) {
+    const card = board.querySelector(`[name="${name}"]`)
+    card.x = x
+    card.y = y
+  }
+})
+```
+
+Connecting and removing are requests that your page applies, because a new
+connection is a new element:
+
+- `helix-connect` names two cards and their sides. Add a `helix-canvas-edge`
+  that joins them.
+- `helix-remove` names the cards and connections to remove, including every
+  connection that removing a card would leave without an end. Remove those
+  elements.
+- `helix-canvas-edit` asks you to edit a card. Open your own editor in it.
+
+Set `readonly` on the board to keep every card in place, or on one card or
+connection to keep only that one.
+
+## Keyboard and screen readers
+
+The board is one tab stop. A card holds it, and Tab leaves the board.
+
+| Keys | On | What they do |
+|---|---|---|
+| Arrow keys | A card or a connection | Move through the cards in reading order, each card's connections straight after it, and select what they land on |
+| Home, End | A card or a connection | Move to the first or the last stop |
+| Control or Command with an arrow key, Home, or End | A card or a connection | Move without changing the selection |
+| Space | A card or a connection | Add it to the selection or take it out |
+| Control or Command with A | A card or a connection | Select everything |
+| Shift with an arrow key | A card | Move the card by 16 units, or to the next multiple of `snap` |
+| Alt with an arrow key | A card | Resize the card from its bottom right corner |
+| Enter or F2 | A card | Ask to edit it, with `helix-canvas-edit`, or edit a group's name |
+| Enter | A connection | Move to the card it arrives at |
+| F2 | A connection | Edit its label |
+| C, then Enter on another card | A card | Ask to connect the two, with `helix-connect` |
+| C | A connection | Pick up its end, to move it to another card with Enter |
+| Delete or Backspace | A card or a connection | Ask to remove what is selected, with `helix-remove` |
+| Control or Command with C, V | The board | Copy the selected cards as JSON Canvas, and paste a document |
+| Control or Command with Z | The board | Undo the last move or resize. With Shift, or Control with Y, make it again |
+| Plus, minus | The board, a card, or a connection | Zoom in or out |
+| Escape | A card or a connection | Stop connecting, or go out to the board |
+| Arrow keys | The board, after Escape | Pan the board |
+
+Every drag also works with clicks. Click a selected card's move handle, a
+corner, a card's connection point, or the end of a selected connection to pick
+it up, then click where it goes. Escape puts it back.
+
+Screen readers meet these roles and names:
+
+| Part | Role | Named by |
+|---|---|---|
+| The board | `group`, described as "canvas" | `label` |
+| A card | `article` | Its content, or its `label` |
+| A group card | `group` | Its `label` |
+| A connection | `button` | "From Draft to Ship", from `connection-label` |
+| The controls | `group` | "Board controls", from `controls-label` |
+| What changed | `status` | The board's own words |
+
+A card is also described by its connections, such as "leads to Ship", and by
+whether it is selected and what its tone means, from `tone-labels`. After a key
+moves, resizes, selects, copies, pastes, undoes, or zooms, screen readers hear
+what changed, such as "Ship moved to 16, 200". Each sentence is a `-label`
+property, so you can write it in your page's language, or register the words
+for a language with `registerWords` (see [Localization](./localization)).
+
+When your page removes the card that has focus, focus moves to the next stop,
+or to the one before when it was the last.

package/content/graphs.mdx

@@ -430,9 +430,16 @@ leaves removing it to your framework.
   whose name starts with it, and Enter or Space selects a note.
 - In the search field, Down moves into the list, and Escape empties the search.
   With `no-panel`, Escape on an empty search closes the list.
+- The legend is a toolbar and one tab stop. Arrow keys, Home, and End move
+  between its groups, typing a letter moves to the next group whose name
+  starts with it, and Space or Enter shows or hides a group.
 - Screen readers read the selected note first, then how each other note links
   to it, such as "Linked from Roadmap". They hear the count when a search or
   the legend changes it.
+- When you select a note, in the list or in the drawing, screen readers hear
+  its name and how many notes the list holds, such as "Roadmap, selected. 4
+  notes", from `selection-label`. A selection your page writes to `active` is
+  not said.
 - After the arrow keys, plus, minus, or the buttons move the drawing, screen
   readers hear which way it went, such as "Moved right" or "Zoomed in".
   `connectGraph` tells the frame once the drawing has moved. If you answer
@@ -441,6 +448,7 @@ leaves removing it to your framework.
 - When you change `nodes` or `links`, the list keeps the note the keys are on.
   When that note is removed, the keys move to the note that took its row.
 - Change the words with `search-label`, `count-label`, `selected-label`,
+  `selection-label`,
   `links-to-label`, `linked-from-label`, `linked-both-label`,
   `moved-up-label`, `moved-down-label`, `moved-left-label`,
   `moved-right-label`, `zoomed-in-label`, and `zoomed-out-label`, or register

package/content/maps.mdx

@@ -642,25 +642,166 @@ compass sets `--map-needle-turn` to the angle that points north, so an icon in
 
 ## Write a driver
 
-To use another renderer, write a driver: an object with two methods.
+To use another renderer, write a driver: an object that moves the renderer's
+view when the frame asks, and tells the frame when the view moved. `connectMap`
+calls it. `mapLibreDriver` and `leafletDriver` are drivers, and the `MapDriver`
+type in `@fusion.dev/helix-map` describes every method.
 
-- `panBy(x, y, motion)` moves the map by a number of pixels.
-- `zoomBy(direction, motion)` zooms in for `1` and out for `-1`.
+### Units
 
-`motion` is your theme's `{ duration, easing }`, or `null` to move without
-animation. Each optional method turns on a feature:
-
-| Method | Turns on |
+| Quantity | Unit |
 |---|---|
-| `project`, `onView` | Placing markers and positions |
-| `show` | Bringing a focused marker into view |
-| `fit` | `connection.fit()` and zooming in to clusters |
-| `layers` | Drawing routes, areas, and points |
-| `credits` | The map credit in the frame's footer |
-| `silenceKeyboard`, `focusTarget`, `replaceZoom` | Using the frame's keys and zoom buttons |
-| `bearing` | Arrows that stay correct when the map is rotated, and the Face north arrow |
-| `rotate`, `tilt` | The rotate, Face north, and tilt buttons and keys |
-| `zoom` | Saying the zoom level after a zoom |
-
-Without `project`, markers stay hidden. To animate a move your page makes
-itself, read the same motion with `motionOf(element, pace)`.
+| A place | `{ lat, lng }` in degrees |
+| A position on screen | CSS pixels from the top left of the renderer's box, right and down positive |
+| Bearing | Degrees clockwise from north |
+| Tilt | Degrees from looking straight down, `0` being flat |
+| Zoom | The renderer's own levels |
+| Motion | `{ duration, easing }`, where `duration` is in milliseconds and `easing(t)` maps 0 to 1 onto 0 to 1, or `null` |
+
+`motion` comes from your theme's motion tokens. It is `null` when the user has
+asked for reduced motion, and the driver then moves at once.
+
+### Required methods
+
+- `panBy(x, y, motion)` moves the view by `x` and `y` CSS pixels. The frame
+  asks for a fraction of its own box, so an arrow key moves the map by the same
+  share of the screen at every zoom. On a right-to-left page, `connectMap`
+  turns the frame's start and end into left and right before it calls the
+  driver.
+- `zoomBy(direction, motion)` zooms one step in, for `1`, or out, for `-1`. A
+  step is whatever the renderer calls one, usually one level.
+
+### Optional methods
+
+Each optional method turns on a feature. Without it, the feature is off and
+nothing fails.
+
+| Method | When `connectMap` calls it | What it must do | Turns on |
+|---|---|---|---|
+| `onView(moved)` | Once, at connect | Call `moved` on every frame the view moves, and return a function that stops | Markers that follow the map, and the announcements after a move |
+| `project(place)` | On every view change, for each marker | Return where `place` falls, in CSS pixels | Placing markers and positions. Without it, markers stay hidden |
+| `zoom()` | After each view change | Return the zoom | Saying "Zoom level 14" after a zoom |
+| `bearing()`, `pitch()` | After each view change | Return the bearing and the tilt | The compass needle, the 3D button's pressed state, and arrows that stay correct on a turned map |
+| `rotate({ by, to }, motion)` | On the rotate buttons, Face north, and Shift with Left or Right | Turn by `by` degrees, or to the bearing `to` | Rotating |
+| `tilt({ by, to }, motion)` | On the 3D button, and Shift with Up or Down | Tilt by `by` degrees, or to `to` | Tilting |
+| `show(place, motion)` | When the keyboard reaches a marker that is off screen | Bring `place` to the middle of the view, at `place.zoom` where it has one | Walking markers off screen |
+| `fit(bounds, padding, motion)` | On `connection.fit()`, and on a press on a cluster | Frame the `northEast` and `southWest` corners, inset by `padding` pixels | `connection.fit()` and zooming in to clusters |
+| `silenceKeyboard()` | Once, at connect | Turn off the renderer's own keys, and return a function that turns them back on | One set of keys |
+| `focusTarget()` | Once, at connect | Return the element the renderer made focusable | One tab stop. `connectMap` sets its `tabindex` to `-1` and puts it back on disconnect |
+| `replaceZoom()` | Once the frame has drawn its zoom buttons | Remove the renderer's zoom buttons, and return a function that puts them back | One set of zoom buttons |
+| `credits(changed)` | Once, at connect | Return `read()`, the credits as markup, and `stop()`; call `changed` when they change | The map credit in the frame's footer |
+| `ready(done)` | Once, at connect | Call `done` when the view is drawn whole, and return a function that stops waiting | `helix-map-ready` and `:state(ready)` |
+| `gestures(mode)` | When the frame's `gestures` changes | Take the wheel and touches as `free`, `cooperative`, or `off` says | Sharing the scroll with the page |
+| `layers(read, events)` | Once, at connect | Draw `read()`, and draw it again on `update()` | Routes, areas, points, and tile layers |
+| `labels(shown)` | When the map type changes | Show or hide the renderer's own roads and names | The Satellite map type |
+| `previews(ask)` | When the layers menu opens after the view moved | Resolve to an image URL for each map type | Pictures in the layers menu |
+| `behind(place)` | With `project` | Return `true` for a place on the far side of a globe | Hiding markers behind a globe |
+
+`connection.disconnect()` calls every function a method returned, gives the
+renderer its gestures back with `gestures('free')`, takes the markers off their
+places, puts the focus target's `tabindex` back as it was, and stops listening
+to the frame. Call it before you remove the renderer.
+
+### How the frame says a move
+
+The frame's keys and buttons only ask. The frame says "Moved left" or "Zoom
+level 14" after the driver calls the `moved` it gave to `onView`, and once the
+view has been still for a moment. A driver without `onView` never makes the
+frame speak, so the frame never describes a move that did not happen.
+
+### Example
+
+This driver shows a plan drawn as one image, such as a floor plan, whose edges
+are at known latitudes and longitudes. It moves the image with a CSS transform,
+places markers, and animates over the page's motion. The same driver runs in
+our specs, so this example stays correct.
+
+```js
+import { connectMap } from '@fusion.dev/helix-map'
+
+const planDriver = (image, plan) => {
+  const view = { scale: 1, x: 0, y: 0 }
+  const listeners = new Set()
+  let moving = 0
+
+  const draw = () => {
+    image.style.transformOrigin = '0 0'
+    image.style.transform = `translate(${view.x}px, ${view.y}px) scale(${view.scale})`
+    for (const moved of listeners) {
+      moved()
+    }
+  }
+
+  // Moves the view to `next` over the page's motion, or at once where it is null.
+  const go = (next, motion) => {
+    const run = ++moving
+    if (!motion || motion.duration <= 0) {
+      Object.assign(view, next)
+      draw()
+      return
+    }
+    const from = { ...view }
+    const start = performance.now()
+    const step = (now) => {
+      if (run !== moving) {
+        return
+      }
+      const t = Math.min(1, (now - start) / motion.duration)
+      const k = motion.easing(t)
+      view.x = from.x + (next.x - from.x) * k
+      view.y = from.y + (next.y - from.y) * k
+      view.scale = from.scale + (next.scale - from.scale) * k
+      draw()
+      if (t < 1) {
+        requestAnimationFrame(step)
+      }
+    }
+    requestAnimationFrame(step)
+  }
+
+  return {
+    onView: (moved) => {
+      listeners.add(moved)
+      return () => listeners.delete(moved)
+    },
+    panBy: (x, y, motion) => go({ ...view, x: view.x - x, y: view.y - y }, motion),
+    project: ({ lat, lng }) => ({
+      x: view.x + ((lng - plan.west) / (plan.east - plan.west)) * plan.width * view.scale,
+      y: view.y + ((plan.north - lat) / (plan.north - plan.south)) * plan.height * view.scale,
+    }),
+    zoom: () => Math.log2(view.scale),
+    zoomBy: (direction, motion) => {
+      const box = image.parentElement.getBoundingClientRect()
+      const k = direction > 0 ? 2 : 0.5
+      const [cx, cy] = [box.width / 2, box.height / 2]
+      go({ scale: view.scale * k, x: cx - (cx - view.x) * k, y: cy - (cy - view.y) * k }, motion)
+    },
+  }
+}
+
+const frame = document.querySelector('helix-map')
+const connection = connectMap(
+  frame,
+  planDriver(frame.querySelector('img'), {
+    east: 0.004,
+    height: 600,
+    north: 51.502,
+    south: 51.5,
+    west: 0,
+    width: 800,
+  }),
+)
+```
+
+`width` and `height` are the image's size in CSS pixels at zoom `0`. To animate
+a move your page makes itself, read the same motion with
+`motionOf(element, pace)`.
+
+### Test a driver
+
+Our specs test each driver twice. A stand-in renderer records what the driver
+asks it, which runs anywhere. Then the browser specs connect a frame to the real
+MapLibre and Leaflet with a style that loads nothing, press the frame's keys and
+buttons, and check that the view moved and that the frame said so. Test your
+driver the same way: connect it to a frame, press a key on the frame's `region`
+part, and wait for the `live` part to say the move.