@fusion.dev/helix-docs 0.197.1 → 0.199.0

package/content/motion.mdx

@@ -92,6 +92,44 @@ The turning `Loader` slows to one turn every four seconds. A loader that stops
 looks broken, and the turn still shows that work is in progress. The pending
 ring on `IconButton` slows the same way.
 
+## Pause the page's motion
+
+Motion that starts by itself and runs longer than five seconds needs a way to
+pause it, under WCAG 2.2.2. `Motion Toggle` pauses all of it on the page at
+once, and a second press lets it run again:
+
+```html
+<helix-motion-toggle>Pause motion</helix-motion-toggle>
+```
+
+While the page's motion is paused:
+
+- `Carousel` stops rotating under `autoplay`.
+- `Video` pauses a video that started itself, and plays it again after.
+- `Aura`, `Orb`, and `Strands` hold the frame they show.
+- A graph that `connectGraph` lays out stops where its notes stand, and its
+  three.js view stops turning.
+- A map layer's `frames` stop on the frame they show.
+
+The choice is the page's, held on the document element as
+`data-helix-motion="paused"`. Set it in your markup to start the page paused,
+or call `pauseMotion` from `@fusion.dev/helix-core`, and select on the
+attribute to pause motion of your own:
+
+```js
+import { pauseMotion } from '@fusion.dev/helix-core'
+
+pauseMotion()
+pauseMotion(false)
+```
+
+With reduced motion set, `Carousel` and `Video` do not start by themselves,
+and a graph lays out its notes with the drawing hidden, then shows them where
+they settle.
+
+A graph layout that runs past five seconds also offers its own button, in the
+graph's frame, that stops it where the notes stand.
+
 ## Starting styles and view transitions
 
 Overlays use `@starting-style` to animate in. It sets a starting value and needs

package/content/spatial-charts.mdx

@@ -6,19 +6,30 @@ title: Spatial charts
 
 # Spatial charts
 
-Helix has three charts drawn in three dimensions. Each reads its numbers from a
+Helix has six charts drawn in three dimensions. Each reads its numbers from a
 table in the document, as every Helix chart does:
 
+- `Spatial Bar Chart` stands a bar for each category and series, each as tall
+  as its value, such as signups by region and by quarter.
 - `Spatial Heatmap` draws a strip of days as a relief, each day a prism as tall
   as its reading.
+- `Spatial Ribbon Chart` draws a ribbon for each series, one behind another,
+  its top following the values across, such as latency by region over two
+  weeks.
 - `Spatial Scatter Chart` places each row as a point in a box, by three measures
   at once.
 - `Spatial Surface Chart` draws one measure as a surface over two others, such
   as load by hour and by day.
+- `Spatial Treemap` shares a floor out among blocks, each as large as one
+  measure and as tall as another, gathered by group, such as each service's
+  requests and its response time.
 
 Each chart draws itself in SVG. `@fusion.dev/helix-plot` can also draw it with
 three.js, in a view you can drag round and zoom.
 
+**Every spatial chart is experimental**, so its API can change.
+[Versioning](./versioning#stability) lists each status.
+
 ## Draw a spatial chart
 
 Put the table in the document, and point the chart at it with `for`:
@@ -48,12 +59,25 @@ Put the table in the document, and point the chart at it with `for`:
 
 Each chart reads its columns in its own way:
 
+- **Spatial Bar Chart** reads its table as `Bar Chart` does: each row is a
+  category, and each numeric column a series. Categories run across and series
+  back in depth, the first series in front, so one series is a single row of
+  bars.
+- **Spatial Ribbon Chart** reads its table as `Line Chart` does: each row is a
+  place along the ribbons, and each numeric column a series. Places run across
+  and series back in depth, the first series in front. A place with no reading
+  ends a ribbon short.
 - **Spatial Scatter Chart** takes the first three numeric columns as across, up,
   and in depth. `group-by` names a column of text that colors each point by its
   group.
 - **Spatial Surface Chart** takes the first numeric column as across, the second
   as depth, and the third as the height. A place on the grid with no reading
   leaves a hole.
+- **Spatial Treemap** takes the first numeric column as each block's size, its
+  share of the floor, and the second as its height. `group-by` names a column
+  of text that gathers its rows into one part of the floor, in one color. With
+  no second numeric column, the blocks stand as one slab. A row with no size
+  is left out.
 - **Spatial Heatmap** reads its table as `Heatmap` does, down each column of
   `rows` and then across. Its table goes inside it.
 
@@ -91,9 +115,12 @@ Each chart has its own connector and driver:
 
 | Chart | Connector | Driver |
 |---|---|---|
+| `Spatial Bar Chart` | `connectSpatialBarChart` | `threeBarDriver` |
 | `Spatial Heatmap` | `connectSpatialHeatmap` | `threeHeatmapDriver` |
+| `Spatial Ribbon Chart` | `connectSpatialRibbonChart` | `threeRibbonDriver` |
 | `Spatial Scatter Chart` | `connectSpatialScatterChart` | `threeScatterDriver` |
 | `Spatial Surface Chart` | `connectSpatialSurfaceChart` | `threeSurfaceDriver` |
+| `Spatial Treemap` | `connectSpatialTreemap` | `threeTreemapDriver` |
 
 `Spatial Heatmap` takes the element in its `renderer` slot, because its table
 is inside it:
@@ -131,10 +158,60 @@ Chromium on an Apple silicon Mac:
 | `Spatial Scatter Chart` | 2,000 points | 5,000 points: 67 ms a turn step |
 | `Spatial Surface Chart` | 900 readings, a grid of 30 by 30 | 1,600 readings: 50 ms, and 3,600: 113 ms |
 | `Spatial Heatmap` | 365 days | 730 days: 50 ms, and 1,825: 132 ms |
+| `Spatial Bar Chart` | 400 bars | 800 bars: 66 ms, and 1,600: 124 ms |
+| `Spatial Ribbon Chart` | 800 readings | 1,600 readings: 50 ms, and 3,200: 83 ms |
+| `Spatial Treemap` | 400 blocks | 800 blocks: 68 ms, and 1,600: 151 ms |
 
 A slower machine reaches these sizes sooner. three.js draws each chart on the
 graphics card.
 
+## Read a place more closely
+
+Two options help you read where a reading stands:
+
+- `drop-lines` on `Spatial Scatter Chart` draws a line from each point straight
+  down to the floor, in its group's color, so where a point stands across and in
+  depth reads off the floor's grid.
+- `contours` on `Spatial Surface Chart` draws the surface's contour lines on it,
+  at each tick of its height, so its shape reads as on a map, and two places at
+  the same height read as such.
+
+three.js draws both as well.
+
+## Draw a chart for a landing page
+
+`no-box` draws `Spatial Bar Chart`, `Spatial Ribbon Chart`, `Spatial Scatter
+Chart`, `Spatial Surface Chart`, or `Spatial Treemap` with no box, grid,
+numbers, or names, and nothing behind it, so the readings stand on the page as
+a picture does:
+
+```html
+<helix-spatial-surface-chart
+  emphasis="outlined"
+  for="load"
+  label="Load over a week"
+  no-box
+></helix-spatial-surface-chart>
+```
+
+The table, the summary, the tooltip, and the keys still carry every value, and
+three.js draws no box either. `Spatial Heatmap` has no box, and its `start` and
+`end` slots are the only names it draws, so leave them empty for the same
+picture.
+
+## When a 3D bar or ribbon chart fits
+
+A flat `Bar Chart` is read more exactly. Studies of 3D bars measure readers
+judging a value less closely than on flat ones, and a bar can stand behind
+another. Use `Spatial Bar Chart` where the shape across two sets of names
+matters more than any one value, such as which regions grew in which quarters.
+A drag turns the view to show a bar another hides, and the tooltip and the
+table carry every exact value.
+
+The same holds for `Spatial Ribbon Chart` beside `Line Chart`. Use it where
+series cross often enough that their lines tangle, and each in its own depth
+reads apart.
+
 ## Read a chart with the pointer and the keys
 
 A pointer resting on a reading shows its row in the chart's tooltip, the same
@@ -154,6 +231,15 @@ The plot takes focus, and the keys move the reading:
 | Enter, Space | Presses the point | Presses the place |
 | Escape | Lets the reading go | Lets the reading go |
 
+`Spatial Bar Chart` reads as `Spatial Surface Chart` does: the left and right
+arrows move from category to category, and the down and up arrows from series to
+series. `Spatial Ribbon Chart` reads the same way, from place to place along a
+ribbon and from ribbon to ribbon.
+
+`Spatial Treemap` reads as `Spatial Scatter Chart` does: the left and right
+arrows move from item to item in the table's order, and the down and up arrows
+among the item's measures.
+
 `Spatial Heatmap` takes `Heatmap`'s keys, and Shift with an arrow turns its
 view, except under `selection-mode="multiple"`, where it selects a range.
 
@@ -161,8 +247,9 @@ In three.js, a step of Shift with an arrow moves over a quarter of a second,
 and with reduced motion set it happens at once. In the SVG drawing, a step
 happens at once, and a drag turns the view as the pointer moves. Both drawings
 turn round the middle of the data and keep their size through a drag, so
-nothing else on the page moves. Once the drag ends, the SVG drawing settles
-into the space that fits it, at once with reduced motion set. No spatial chart
+nothing else on the page moves. Once a drag or a step ends, each settles into
+the space that fits it, at once with reduced motion set. three.js keeps the
+zoom you chose. No spatial chart
 turns by itself.
 
 The numbers and names stand outside the box, along the edges that face the
@@ -174,17 +261,36 @@ the two ends of its front edge, clear of the relief.
 
 Each chart takes its colors from your theme, and these hooks change them:
 
+- **Spatial Bar Chart**: each series takes a series color,
+  `--chart-series-1` and on, and each face of a bar is that color darkened by
+  how far it turns from the light.
+- **Spatial Ribbon Chart**: each series takes a series color, `--chart-series-1`
+  and on, and each face of a ribbon is that color darkened by how far it turns
+  from the light.
 - **Spatial Scatter Chart**: each group takes a series color,
   `--chart-series-1` and on.
 - **Spatial Surface Chart**: the surface is shaded from `--spatial-surface-chart-low`
   to `--spatial-surface-chart-high`.
+- **Spatial Treemap**: each group takes a series color, `--chart-series-1` and
+  on, and each face of a block is that color darkened by how far it turns from
+  the light.
 - **Spatial Heatmap**: each day takes its tone's color, as on `Heatmap`:
   `--heatmap-tone-1` to `--heatmap-tone-5` along the ramp, or a named tone such
   as `--heatmap-tone-success`. `--spatial-heatmap-left-shade` and
   `--spatial-heatmap-right-shade` set how much less light each side of a prism
   is than its top.
 
-three.js reads the same colors, so the two drawings agree. It lights the
+`emphasis` and `material` change how the marks are drawn, as on every chart:
+
+- `emphasis="outlined"` draws each mark as its edge over a fill faded toward
+  the page. On `Spatial Surface Chart` it is a wireframe.
+- `emphasis="subtle"` draws a faint wash under the same edge, which shows what
+  stands behind a prism, a point, or a fold of the surface.
+- `material="glass"` lets the most of what is behind each mark through, and
+  `material="frosted"` less.
+
+three.js reads the same colors, `emphasis`, and `material`, so the two drawings
+agree. It lights the
 prisms and the surface itself, so the two shade hooks apply to the SVG drawing
 alone.