@fusion.dev/helix-docs 0.184.0 → 0.186.0

package/content/building-on-the-headless-tier.mdx

@@ -53,11 +53,11 @@ open.
 
 [//]: # (renders)
 
-**31 of the 98 headless families interpolate another family's tag**, across 22 distinct children.
+**32 of the 99 headless families interpolate another family's tag**, across 22 distinct children.
 
 | Family | Renders |
 |---|---|
-| `area-chart`, `bar-chart`, `copy-button`, `donut-chart`, `heatmap`, `line-chart`, `scatter-chart` | `tooltip` |
+| `area-chart`, `bar-chart`, `copy-button`, `donut-chart`, `heatmap`, `isometric-heatmap`, `line-chart`, `scatter-chart` | `tooltip` |
 | `breadcrumbs` | `breadcrumb` |
 | `chat` | `chat-message` |
 | `checkbox-group`, `table` | `checkbox` |

package/content/charting.mdx

@@ -14,6 +14,7 @@ Helix has these chart families, and each one has its own API page:
 - `Scatter Chart`
 - `Donut Chart`
 - `Heatmap`
+- `Isometric Heatmap`
 - `Sparkline`
 - `Trend`
 - `Legend`, which all of the charts share
@@ -39,6 +40,11 @@ Choose a chart by the question it answers.
 - **Whether two measures relate.** `Scatter Chart`, with one point per row.
 - **How each day or check went.** `Heatmap`, for uptime, contributions, or
   activity.
+- **The same days, as a relief.** `Isometric Heatmap` reads the same table as
+  `Heatmap` and draws each reading as a prism as tall as its value. Use it where
+  the overall shape matters more than any one exact value, such as a busy
+  stretch in a year of commits. The tooltip and the table carry the exact
+  values.
 - **The shape of a series beside its number.** `Sparkline`, drawn with no axes.
   Use `Trend` to show which way one measurement moved and whether that is good
   news.

package/content/graphs.mdx

@@ -1,5 +1,5 @@
 ---
-description: Add interactive graphs to your site, styled with your theme and drawn by Sigma.js, cosmos.gl, or three.js.
+description: Add interactive graphs and isometric diagrams to your site, styled with your theme and drawn by Sigma.js, cosmos.gl, three.js, or Helix.
 section: Essentials
 title: Graphs
 ---
@@ -7,7 +7,7 @@ title: Graphs
 # Graphs
 
 Helix Graph puts a frame around a graph drawn by Sigma.js, cosmos.gl, three.js,
-or a renderer of your own. The frame adds a searchable list of every note, zoom
+a renderer of your own, or Helix's own isometric diagram. The frame adds a searchable list of every note, zoom
 and fullscreen buttons, and keyboard controls. You give the frame notes and
 links, and `@fusion.dev/helix-graph` draws them with the renderer, colored by
 your theme.
@@ -81,6 +81,7 @@ thousands of notes written as markup would be thousands of elements.
 | Sigma.js | Graphs of thousands of notes | `sigma graphology graphology-layout-forceatlas2` | `sigmaDriver` from `@fusion.dev/helix-graph/sigma` |
 | cosmos.gl | Graphs of tens of thousands of notes or more, laid out on the GPU | `@cosmos.gl/graph` | `cosmosDriver` from `@fusion.dev/helix-graph/cosmos` |
 | three.js | Graphs in 3D, and graphs on the surface of a 3D model | `three d3-force-3d` | `threeDriver` from `@fusion.dev/helix-graph/three` |
+| Helix, in SVG | Architecture and flow diagrams of up to a few hundred notes, drawn as solids on an isometric floor | Nothing more | `isometricDriver` from `@fusion.dev/helix-graph/isometric` |
 
 None of the renderers is bundled with Helix, so you can use the version you
 already have.
@@ -105,9 +106,78 @@ const connection = connectGraph(frame, threeDriver(frame.querySelector('div')))
 ```
 
 Drag to turn a 3D graph, and use the wheel or a pinch to zoom. It turns slowly
-on its own until someone handles it, unless they asked for reduced motion. Set
+on its own for its first five seconds, and stops as soon as someone handles it.
+It does not turn for a reader who asked for reduced motion. Set
 `autoRotate: false` to keep it still.
 
+A 3D graph draws only while something moves. Every 3D graph on a page shares
+six WebGL contexts: past six, a graph far off screen gives its context back
+and takes it again as it comes near.
+
+## Draw an isometric diagram
+
+`isometricDriver` draws the graph as an isometric diagram in SVG, with nothing
+more to install. Pass it the box:
+
+```js
+import { isometricDriver } from '@fusion.dev/helix-graph/isometric'
+
+frame.nodes = [
+  { id: 'gateway', label: 'API gateway', group: 'Edge', x: 0, y: 0 },
+  { id: 'orders', label: 'Orders', group: 'Services', x: 3, y: 0 },
+  { id: 'ledger', label: 'Order ledger', group: 'Data', shape: 'circle', x: 6, y: 0 },
+]
+frame.links = [
+  { source: 'gateway', target: 'orders' },
+  { source: 'orders', target: 'ledger' },
+]
+const connection = connectGraph(frame, isometricDriver(frame.querySelector('div')))
+```
+
+- **Each note stands on a cell of the floor** at its `x` and `y`: `x` runs
+  across, and `y` runs back. When no note gives a place, the driver lays the
+  notes out in columns along the links, sources first. A note added without a
+  place goes to the nearest free cell beside the notes it links to.
+- **A note's `shape` picks its solid.** `square` is a block, which is the
+  default, `circle` is a cylinder, and `diamond` is a pyramid. Its `size` sets
+  its height.
+- **Each face is shaded from the note's color**, so the diagram takes your
+  theme. Each group stands on a plate of its color, with its name written on
+  the floor.
+- **Links run along the floor**, with an arrow halfway that points the way the
+  link runs.
+
+Drag to pan, and use the wheel to zoom. Set `flat: true` to draw every note at
+no height. The drawing moves only when the reader moves it, so there is no
+motion to pause.
+
+### Turn and tilt the view
+
+`turn` is the compass bearing the diagram is seen from, in degrees, and `tilt`
+is the camera's height above the floor. The defaults are the isometric view:
+`turn: 45`, the front left corner, and `tilt: 35.26`. `tilt` runs from 15 to
+90, which is a plan seen from straight above.
+
+```js
+const driver = isometricDriver(box, { turn: 20, tilt: 55 })
+connectGraph(frame, driver)
+
+driver.turnBy(90) // brings the next corner round to the front
+driver.turnTo({ tilt: 90 }) // looks from straight above
+```
+
+- **The faces and the light follow the camera.** Each solid shows the faces
+  turned toward the camera, and the light falls from the upper left of the
+  page.
+- **A diagram seen whole stays whole** as it turns. Otherwise the view turns
+  about the middle of the box.
+- **Shift with a drag** turns the view across and tilts it up and down.
+- **`turnBy` and `turnTo` animate**, unless the reader asked for reduced
+  motion.
+
+Give your turn buttons labels that name the diagram, such as "Turn the diagram
+left".
+
 ## Free the renderer
 
 Call `connection.disconnect()` when the graph leaves the page, then free the

package/content/iconography.mdx

@@ -17,36 +17,15 @@ Phosphor. We use the bold weight because Phosphor's regular weight is a
 hairline beside the medium weight of Helix text. An icon that looks lighter than
 the words next to it does not work as a mark.
 
-## Register the names a page draws
+## Register the set
 
 ```ts
 import '@fusion.dev/helix/icon'
 ```
 
-The family's entry registers thirteen names, the glyphs a control most often
-needs: `caret-down`, `caret-left`, `caret-right`, `caret-up`, `arrow-left`,
-`arrow-right`, `check`, `x`, `plus`, `minus`, `magnifying-glass`, `info` and
-`warning`. They cost about 700 bytes gzipped.
-
-```ts
-import '@fusion.dev/helix/icon/all'
-```
-
-`icon/all` registers all 126 names, for 15 kB gzipped. Import it when a page
-draws glyphs outside the thirteen by name, such as `trash` above. A name that
-resolves to nothing draws nothing, fires `error`, and prints a warning that
-names this entry. `import '@fusion.dev/helix'`, which registers every element,
-registers every name too.
-
-`icon/root` registers no names. Import it with `registerIcons` to ship exactly
-the glyphs you name:
-
-```ts
-import { registerIcons } from '@fusion.dev/helix/icon/root'
-import { gear, trash } from '@fusion.dev/helix-icons'
-
-registerIcons([gear, trash])
-```
+The Icon entry registers all 126 glyphs by name, so `name` draws any glyph in
+the set. `@fusion.dev/helix/icon/all` is the same entry and registers the same
+set.
 
 ## Size and color come from the surrounding text
 
@@ -119,9 +98,10 @@ import { trash } from '@fusion.dev/helix-icons'
 string. Frameworks can set properties. Plain HTML cannot, so it uses `name`. If
 both are set, `icon` wins.
 
-`icon` also keeps your bundle small. `name` looks up glyphs in an index, and no
-bundler can tree-shake an index. With `icon`, you ship only the glyph you
-import.
+`icon` also keeps your bundle small. `name` looks up glyphs in an index of the
+whole set, and no bundler can tree-shake that index. If you render one icon by
+`name`, you ship the whole set: 17 kB gzipped for 126 glyphs. With `icon`, you
+ship only the glyph you import.
 
 `icon` also draws glyphs from outside this set. Anything that exports the same
 shape works:
@@ -148,7 +128,7 @@ Phosphor's weights are outlined, filled paths. `caret-down` is `a12,12` at bold
 and `a8,8` at regular, so CSS cannot turn one weight into another, and every
 weight offered adds bytes. Bundlers tree-shake a subpath at each import site. A
 `weight` attribute would put every weight into the index that `name` reads, and
-raise `icon/all` from 15 kB to about 90.
+raise your bundle from 15 kB to about 90.
 
 Only the default weight has that index, so `name` always draws bold. To use the
 set in another weight, import the glyphs and pass them to `icon`.