@fusion.dev/helix-plot 0.198.0 → 0.199.1

package/README.md

@@ -1,10 +1,13 @@
 # @fusion.dev/helix-plot
 
-Connects the Helix `Spatial Heatmap`, `Spatial Scatter Chart` and
-`Spatial Surface Chart` to three.js, which draws them in three dimensions,
-lit, in a view you can drag round and zoom, colored from your tokens. Each
+Connects the Helix spatial charts to three.js, which draws them in three
+dimensions, lit, in a view you can drag round and zoom, colored from your
+tokens: `Spatial Bar Chart`, `Spatial Heatmap`, `Spatial Ribbon Chart`,
+`Spatial Scatter Chart`, `Spatial Surface Chart`, and `Spatial Treemap`. Each
 also draws itself in SVG, which this package replaces where it is connected.
 
+The spatial charts and this package are experimental, so their API can change.
+
 ```sh
 bun add @fusion.dev/helix @fusion.dev/helix-plot three
 ```
@@ -98,6 +101,102 @@ const connection = connectSpatialSurfaceChart(chart, threeSurfaceDriver(chart.qu
 |---|---|---|
 | `density` | screen × 1.5, 2 to 3; on a touch screen, the screen's own, at most 2 | How many pixels the drawing has for each of the page's |
 
+## Bars
+
+`Spatial Bar Chart` connects the same way:
+
+```html
+<table id="signups">…</table>
+
+<helix-spatial-bar-chart for="signups" label="Signups by region and quarter">
+  <div></div>
+</helix-spatial-bar-chart>
+```
+
+```js
+import '@fusion.dev/helix/spatial-bar-chart'
+import { connectSpatialBarChart } from '@fusion.dev/helix-plot'
+import { threeBarDriver } from '@fusion.dev/helix-plot/three'
+
+const chart = document.querySelector('helix-spatial-bar-chart')
+const connection = connectSpatialBarChart(chart, threeBarDriver(chart.querySelector('div')))
+```
+
+- **The chart reads its table as `Bar Chart` does.** Each row is a category
+  and each numeric column a series. The bars stand on a grid of categories
+  across and series in depth, the first series in front, each from zero to its
+  value. The box takes the grid's proportions, so one series is a long, low
+  row.
+- **Each series takes a series color**, `--chart-series-1` and on, lit from
+  above.
+- **A bar the mouse rests on, or one tapped or pressed, is the chart's
+  reading**, ringed and shown in the chart's tooltip. The left and right arrows
+  move from category to category, and the down and up arrows from series to
+  series.
+- The box, the turning, the frames, and the shared contexts are the scatter's.
+
+| `threeBarDriver` option | Default | What else it takes |
+|---|---|---|
+| `density` | screen × 1.5, 2 to 3; on a touch screen, the screen's own, at most 2 | How many pixels the drawing has for each of the page's |
+
+## Ribbons
+
+`Spatial Ribbon Chart` connects the same way, with `connectSpatialRibbonChart`
+and `threeRibbonDriver`:
+
+```js
+import '@fusion.dev/helix/spatial-ribbon-chart'
+import { connectSpatialRibbonChart } from '@fusion.dev/helix-plot'
+import { threeRibbonDriver } from '@fusion.dev/helix-plot/three'
+
+const chart = document.querySelector('helix-spatial-ribbon-chart')
+const connection = connectSpatialRibbonChart(chart, threeRibbonDriver(chart.querySelector('div')))
+```
+
+- **The chart reads its table as `Line Chart` does.** Each row is a place
+  along the ribbons and each numeric column a series, one ribbon behind
+  another, the first in front, in a box long across and shallow in depth.
+- **Each series takes a series color**, `--chart-series-1` and on, lit from
+  above.
+- **A reading the mouse rests on, or one tapped or pressed, is the chart's
+  reading**, ringed and shown in the chart's tooltip. The left and right
+  arrows move along a ribbon, and the down and up arrows from ribbon to
+  ribbon.
+- The box, the turning, the frames, and the shared contexts are the scatter's.
+
+| `threeRibbonDriver` option | Default | What else it takes |
+|---|---|---|
+| `density` | screen × 1.5, 2 to 3; on a touch screen, the screen's own, at most 2 | How many pixels the drawing has for each of the page's |
+
+## A treemap
+
+`Spatial Treemap` connects the same way, with `connectSpatialTreemap` and
+`threeTreemapDriver`:
+
+```js
+import '@fusion.dev/helix/spatial-treemap'
+import { connectSpatialTreemap } from '@fusion.dev/helix-plot'
+import { threeTreemapDriver } from '@fusion.dev/helix-plot/three'
+
+const chart = document.querySelector('helix-spatial-treemap')
+const connection = connectSpatialTreemap(chart, threeTreemapDriver(chart.querySelector('div')))
+```
+
+- **The chart shares its floor out among its rows.** The first numeric column
+  is each block's size, its share of the floor, and the second its height.
+  `group-by` names a column of text that gathers rows into one part of the
+  floor.
+- **Each group takes a series color**, `--chart-series-1` and on, lit from
+  above.
+- **A block the mouse rests on, or one tapped or pressed, is the chart's
+  reading**, ringed and shown in the chart's tooltip. The left and right
+  arrows move from block to block in the table's order.
+- The box, the turning, the frames, and the shared contexts are the scatter's.
+
+| `threeTreemapDriver` option | Default | What else it takes |
+|---|---|---|
+| `density` | screen × 1.5, 2 to 3; on a touch screen, the screen's own, at most 2 | How many pixels the drawing has for each of the page's |
+
 ## A heatmap
 
 `Spatial Heatmap` takes the renderer's box in its `renderer` slot, since its
@@ -141,7 +240,7 @@ const connection = connectSpatialHeatmap(chart, threeHeatmapDriver(box))
 
 | Import | What |
 |---|---|
-| `@fusion.dev/helix-plot` | `connectSpatialHeatmap(chart, driver)`, `connectSpatialScatterChart(chart, driver)`, `connectSpatialSurfaceChart(chart, driver)`, `plotColorsFrom(chart, groups, extra)`, and the types `Axes`, `Axis`, `Field`, `HeatmapCell`, `Place`, `PlotColors`, `PlotConnection`, `PlotDriver`, `Point`, `PointerKind`, `SpatialHeatmapConnection`, `SpatialHeatmapDriver`, `SpatialHeatmapField`, `SpatialScatterChartConnection`, `SpatialScatterChartDriver`, `SpatialSurfaceChartConnection`, `SpatialSurfaceChartDriver`, `SurfaceCell` and `SurfaceField` |
-| `@fusion.dev/helix-plot/three` | `threeHeatmapDriver(box, options)`, `threeScatterDriver(box, options)` and `threeSurfaceDriver(box, options)`, and the types `ThreeHeatmapDriverOptions`, `ThreeScatterDriverOptions` and `ThreeSurfaceDriverOptions` |
+| `@fusion.dev/helix-plot` | `connectSpatialBarChart(chart, driver)`, `connectSpatialHeatmap(chart, driver)`, `connectSpatialRibbonChart(chart, driver)`, `connectSpatialScatterChart(chart, driver)`, `connectSpatialSurfaceChart(chart, driver)`, `connectSpatialTreemap(chart, driver)`, `plotColorsFrom(chart, groups, extra)`, and the types `Axes`, `Axis`, `BarCell`, `BarField`, `Corners`, `Field`, `HeatmapCell`, `Place`, `PlotColors`, `PlotConnection`, `PlotDriver`, `Point`, `PointerKind`, `RibbonCell`, `RibbonField`, `SpatialBarChartConnection`, `SpatialBarChartDriver`, `SpatialHeatmapConnection`, `SpatialHeatmapDriver`, `SpatialHeatmapField`, `SpatialRibbonChartConnection`, `SpatialRibbonChartDriver`, `SpatialScatterChartConnection`, `SpatialScatterChartDriver`, `SpatialSurfaceChartConnection`, `SpatialSurfaceChartDriver`, `SpatialTreemapConnection`, `SpatialTreemapDriver`, `SurfaceCell`, `SurfaceField`, `TreemapBlock`, and `TreemapField` |
+| `@fusion.dev/helix-plot/three` | `threeBarDriver(box, options)`, `threeHeatmapDriver(box, options)`, `threeRibbonDriver(box, options)`, `threeScatterDriver(box, options)`, `threeSurfaceDriver(box, options)`, and `threeTreemapDriver(box, options)`, and the types `ThreeBarDriverOptions`, `ThreeHeatmapDriverOptions`, `ThreeRibbonDriverOptions`, `ThreeScatterDriverOptions`, `ThreeSurfaceDriverOptions`, and `ThreeTreemapDriverOptions` |
 
 **three.js is an optional peer**, so a page brings the version it has. `@fusion.dev/helix-plot` itself never imports it: only `@fusion.dev/helix-plot/three` does, so a page with a driver of its own needs no three.js.

package/dist/connect-plot/connect-plot.d.ts

@@ -1,11 +1,21 @@
 /** One axis of a plot: its column's name, its range, and the ticks on it. */
 export interface Axis {
+    /** The words written at the ticks, for an axis of names such as a bar chart's categories. */
+    labels?: readonly string[] | undefined;
     name: string;
     range: readonly [number, number];
+    /** Where the grid's lines run along this axis, where not at the ticks. */
+    rules?: readonly number[] | undefined;
     ticks: readonly number[];
 }
 /** A plot's three axes: across, up, and in depth. */
 export interface Axes {
+    /**
+     * How long the box is along each axis, across, up, and in depth, as a share
+     * of the cube's, where a chart's grid is not square: `[1, 1, 1]` where it
+     * does not say.
+     */
+    readonly extent?: readonly [number, number, number] | undefined;
     readonly x: Axis;
     readonly y: Axis;
     readonly z: Axis;
@@ -25,6 +35,27 @@ export interface PlotColors {
     groups: string[];
     /** The names and the ring on what the keys rest on: `foreground`. */
     ink: string;
+    /**
+     * How the marks are drawn, from the chart's `emphasis` and `material`, as
+     * the chart's own drawing reads them: `emphasis` is `solid`, `outlined` (an
+     * edge in the mark's color over a fill faded toward `page`) or `subtle` (a
+     * faint wash under that edge), and `through` how much of the mark comes
+     * through, 1 with no material, `glass` 0.62 and `frosted` 0.88, times the
+     * theme's `--helix-material-opacity`. `box` is whether the box, its grid,
+     * and its numbers and names are drawn, which the chart's `no-box` turns off.
+     * `contours` and `drops` are whether a surface's contour lines and a
+     * scatter's lines down to the floor are drawn, as its `contours` and
+     * `drop-lines` ask.
+     */
+    look: {
+        box: boolean;
+        contours: boolean;
+        drops: boolean;
+        emphasis: 'outlined' | 'solid' | 'subtle';
+        through: number;
+    };
+    /** The page a faded fill moves toward: `background`. */
+    page: string;
     /** The ticks' numbers: `foreground-muted`. */
     quiet: string;
     /**

package/dist/connect-plot/connect-plot.js

@@ -24,15 +24,27 @@ export const plotColorsFrom = (chart, groups, extra = {}) => {
                 ? null
                 : read(`var(--helix-color-${name})`);
         };
-        const [grid, ground, ink, quiet] = [
+        const [grid, ground, ink, quiet, page] = [
             'border',
             'surface-sunken',
             'foreground',
             'foreground-muted',
+            'background',
         ].map(token);
         if (!grid || !ground || !ink || !quiet) {
             return null;
         }
+        const emphasis = chart.getAttribute('emphasis');
+        const material = chart.getAttribute('material');
+        const strength = Number.parseFloat(getComputedStyle(chart).getPropertyValue('--helix-material-opacity'));
+        const scale = Number.isFinite(strength) ? strength : 1;
+        const look = {
+            box: !chart.hasAttribute('no-box'),
+            contours: chart.hasAttribute('contours'),
+            drops: chart.hasAttribute('drop-lines'),
+            emphasis: emphasis === 'outlined' || emphasis === 'subtle' ? emphasis : 'solid',
+            through: material === 'glass' ? 0.62 * scale : material === 'frosted' ? 0.88 * scale : 1,
+        };
         const colors = [];
         for (let at = 0; at < Math.max(groups, 1); at++) {
             colors.push(read(`var(--chart-series-${(at % SERIES) + 1}, var(--helix-color-primary))`) ?? ink);
@@ -43,7 +55,17 @@ export const plotColorsFrom = (chart, groups, extra = {}) => {
         for (const [name, value] of Object.entries(extra)) {
             named[name] = read(value) ?? ink;
         }
-        return { extra: named, grid, ground, groups: colors, ink, quiet, ramp: { high, low } };
+        return {
+            extra: named,
+            grid,
+            ground,
+            groups: colors,
+            ink,
+            look,
+            page: page ?? ground,
+            quiet,
+            ramp: { high, low },
+        };
     }
     finally {
         probe.remove();
@@ -108,6 +130,15 @@ export const connectPlot = (frame, driver, options) => {
     const stopTheme = watchTheme(frame, () => {
         draw();
     });
+    const looks = typeof MutationObserver === 'function'
+        ? new MutationObserver(() => {
+            draw();
+        })
+        : undefined;
+    looks?.observe(frame, {
+        attributeFilter: ['contours', 'drop-lines', 'emphasis', 'material', 'no-box'],
+        attributes: true,
+    });
     void Promise.resolve(chart.updateComplete).then(draw);
     return {
         disconnect: () => {
@@ -121,6 +152,7 @@ export const connectPlot = (frame, driver, options) => {
             chart.placeReading?.(undefined);
             chart.placeCorners?.(undefined);
             stopTheme();
+            looks?.disconnect();
             driver.stop?.();
             chart.rendererDrawn?.(false);
         },

package/dist/connect-spatial-bar-chart/connect-spatial-bar-chart.d.ts

@@ -0,0 +1,39 @@
+import { type Axes, type PlotConnection, type PlotDriver } from '../connect-plot/connect-plot.js';
+/** One place on a bar chart's grid: a category across, a series in depth, and its value, where the table has one. */
+export interface BarCell {
+    across: number;
+    column: number;
+    depth: number;
+    label: string;
+    row: number;
+    value?: number | undefined;
+}
+/**
+ * What a Spatial Bar Chart publishes for a renderer to draw: every place on
+ * its grid, across first, so the bar for category `across` in series
+ * `depth` is `cells[across * series.length + depth]`, and its axes, whose
+ * `extent` gives the box the grid's proportions.
+ */
+export interface BarField {
+    axes: Axes;
+    categories: readonly string[];
+    cells: readonly BarCell[];
+    readings: number;
+    series: readonly string[];
+}
+/** A renderer for a Spatial Bar Chart: `focus` and `onPress` take a bar's index in `field.cells`. */
+export type SpatialBarChartDriver = PlotDriver<BarField>;
+/** A connection between a Spatial Bar Chart and its renderer. */
+export type SpatialBarChartConnection = PlotConnection;
+/**
+ * Connects a Spatial Bar Chart to whatever draws it in three dimensions.
+ *
+ * The chart is `helix-spatial-bar-chart` or `helix-headless-spatial-bar-chart`,
+ * and the driver is `threeBarDriver` from `@fusion.dev/helix-plot/three`, or
+ * one of your own. The connection draws the chart's bars in the driver, each
+ * series in a series color, marks the bar the keys rest on, turns the view
+ * for Shift with an arrow, and puts a bar pressed in the drawing on the
+ * chart's reading. Once the driver has drawn, the chart hides its own SVG
+ * drawing; `disconnect()` shows it again.
+ */
+export declare const connectSpatialBarChart: (frame: HTMLElement, driver: SpatialBarChartDriver) => SpatialBarChartConnection;

package/dist/connect-spatial-bar-chart/connect-spatial-bar-chart.js

@@ -0,0 +1,6 @@
+import { connectPlot, } from '../connect-plot/connect-plot.js';
+export const connectSpatialBarChart = (frame, driver) => connectPlot(frame, driver, {
+    groupsOf: (field) => field.series.length,
+    name: 'connectSpatialBarChart',
+    readings: (field) => field.readings,
+});

package/dist/connect-spatial-ribbon-chart/connect-spatial-ribbon-chart.d.ts

@@ -0,0 +1,39 @@
+import { type Axes, type PlotConnection, type PlotDriver } from '../connect-plot/connect-plot.js';
+/** One reading of a ribbon chart: a place across, a series in depth, and its value, where the table has one. */
+export interface RibbonCell {
+    across: number;
+    column: number;
+    depth: number;
+    label: string;
+    row: number;
+    value?: number | undefined;
+}
+/**
+ * What a Spatial Ribbon Chart publishes for a renderer to draw: every
+ * reading, across first, so the reading at place `across` in series `depth`
+ * is `cells[across * series.length + depth]`, and its axes, whose `extent`
+ * makes the box long across and shallow in depth.
+ */
+export interface RibbonField {
+    axes: Axes;
+    categories: readonly string[];
+    cells: readonly RibbonCell[];
+    readings: number;
+    series: readonly string[];
+}
+/** A renderer for a Spatial Ribbon Chart: `focus` and `onPress` take a reading's index in `field.cells`. */
+export type SpatialRibbonChartDriver = PlotDriver<RibbonField>;
+/** A connection between a Spatial Ribbon Chart and its renderer. */
+export type SpatialRibbonChartConnection = PlotConnection;
+/**
+ * Connects a Spatial Ribbon Chart to whatever draws it in three dimensions.
+ *
+ * The chart is `helix-spatial-ribbon-chart` or
+ * `helix-headless-spatial-ribbon-chart`, and the driver is `threeRibbonDriver`
+ * from `@fusion.dev/helix-plot/three`, or one of your own. The connection
+ * draws the chart's ribbons in the driver, each series in a series color,
+ * marks the reading the keys rest on, turns the view for Shift with an
+ * arrow, and puts a reading pressed in the drawing on the chart's reading. Once the driver has drawn, the chart hides its own SVG
+ * drawing; `disconnect()` shows it again.
+ */
+export declare const connectSpatialRibbonChart: (frame: HTMLElement, driver: SpatialRibbonChartDriver) => SpatialRibbonChartConnection;

package/dist/connect-spatial-ribbon-chart/connect-spatial-ribbon-chart.js

@@ -0,0 +1,6 @@
+import { connectPlot, } from '../connect-plot/connect-plot.js';
+export const connectSpatialRibbonChart = (frame, driver) => connectPlot(frame, driver, {
+    groupsOf: (field) => field.series.length,
+    name: 'connectSpatialRibbonChart',
+    readings: (field) => field.readings,
+});

package/dist/connect-spatial-surface-chart/connect-spatial-surface-chart.d.ts

@@ -16,7 +16,15 @@ export interface SurfaceField {
     acrosses: readonly number[];
     axes: Axes;
     cells: readonly SurfaceCell[];
+    /** The contour lines at each tick of the height, each segment two places across and in depth, which `contours` draws on the surface. */
+    contours?: readonly {
+        level: number;
+        segments: readonly (readonly [readonly [number, number], readonly [number, number]])[];
+    }[];
     depths: readonly number[];
+    /** The lowest and the highest reading. */
+    highest?: number;
+    lowest?: number;
     readings: number;
 }
 /** A renderer for a Spatial Surface Chart: `focus` and `onPress` take a place's index in `field.cells`. */

package/dist/connect-spatial-treemap/connect-spatial-treemap.d.ts

@@ -0,0 +1,47 @@
+import { type Axes, type PlotConnection, type PlotDriver } from '../connect-plot/connect-plot.js';
+/** One row of a treemap drawn as a block: its part of the floor, its size, its height where the table has one, and its group. */
+export interface TreemapBlock {
+    /** Its part of the floor, across from `x0` to `x1` and in depth from `z0` to `z1`, each from -1 to 1. */
+    area: {
+        x0: number;
+        x1: number;
+        z0: number;
+        z1: number;
+    };
+    group: string;
+    groupIndex: number;
+    height?: number | undefined;
+    label: string;
+    row: number;
+    size: number;
+}
+/**
+ * What a Spatial Treemap publishes for a renderer to draw: every block, in
+ * the table's order, each on its part of the floor, and the axes, whose `y`
+ * is the height and whose `extent` gives the box its proportions. `height`
+ * is `''` where no column gives one, and each block is then a slab as tall
+ * as the box.
+ */
+export interface TreemapField {
+    axes: Axes;
+    blocks: readonly TreemapBlock[];
+    groups: readonly string[];
+    height: string;
+    size: string;
+}
+/** A renderer for a Spatial Treemap: `focus` and `onPress` take a block's index in `field.blocks`. */
+export type SpatialTreemapDriver = PlotDriver<TreemapField>;
+/** A connection between a Spatial Treemap and its renderer. */
+export type SpatialTreemapConnection = PlotConnection;
+/**
+ * Connects a Spatial Treemap to whatever draws it in three dimensions.
+ *
+ * The chart is `helix-spatial-treemap` or `helix-headless-spatial-treemap`,
+ * and the driver is `threeTreemapDriver` from `@fusion.dev/helix-plot/three`,
+ * or one of your own. The connection draws the chart's blocks in the driver,
+ * each group in a series color, marks the block the keys rest on, turns the
+ * view for Shift with an arrow, and puts a block pressed in the drawing on
+ * the chart's reading. Once the driver has drawn, the chart hides its own SVG
+ * drawing; `disconnect()` shows it again.
+ */
+export declare const connectSpatialTreemap: (frame: HTMLElement, driver: SpatialTreemapDriver) => SpatialTreemapConnection;

package/dist/connect-spatial-treemap/connect-spatial-treemap.js

@@ -0,0 +1,6 @@
+import { connectPlot, } from '../connect-plot/connect-plot.js';
+export const connectSpatialTreemap = (frame, driver) => connectPlot(frame, driver, {
+    groupsOf: (field) => field.groups.length,
+    name: 'connectSpatialTreemap',
+    readings: (field) => field.blocks.length,
+});

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 export { type Axes, type Axis, type Corners, type Place, type PlotColors, type PlotConnection, type PlotDriver, type PointerKind, plotColorsFrom, } from './connect-plot/connect-plot.js';
+export { type BarCell, type BarField, connectSpatialBarChart, type SpatialBarChartConnection, type SpatialBarChartDriver, } from './connect-spatial-bar-chart/connect-spatial-bar-chart.js';
 export { connectSpatialHeatmap, type HeatmapCell, type SpatialHeatmapConnection, type SpatialHeatmapDriver, type SpatialHeatmapField, } from './connect-spatial-heatmap/connect-spatial-heatmap.js';
+export { connectSpatialRibbonChart, type RibbonCell, type RibbonField, type SpatialRibbonChartConnection, type SpatialRibbonChartDriver, } from './connect-spatial-ribbon-chart/connect-spatial-ribbon-chart.js';
 export { connectSpatialScatterChart, type Field, type Point, type SpatialScatterChartConnection, type SpatialScatterChartDriver, } from './connect-spatial-scatter-chart/connect-spatial-scatter-chart.js';
 export { connectSpatialSurfaceChart, type SpatialSurfaceChartConnection, type SpatialSurfaceChartDriver, type SurfaceCell, type SurfaceField, } from './connect-spatial-surface-chart/connect-spatial-surface-chart.js';
+export { connectSpatialTreemap, type SpatialTreemapConnection, type SpatialTreemapDriver, type TreemapBlock, type TreemapField, } from './connect-spatial-treemap/connect-spatial-treemap.js';

package/dist/index.js

@@ -1,4 +1,7 @@
 export { plotColorsFrom, } from './connect-plot/connect-plot.js';
+export { connectSpatialBarChart, } from './connect-spatial-bar-chart/connect-spatial-bar-chart.js';
 export { connectSpatialHeatmap, } from './connect-spatial-heatmap/connect-spatial-heatmap.js';
+export { connectSpatialRibbonChart, } from './connect-spatial-ribbon-chart/connect-spatial-ribbon-chart.js';
 export { connectSpatialScatterChart, } from './connect-spatial-scatter-chart/connect-spatial-scatter-chart.js';
 export { connectSpatialSurfaceChart, } from './connect-spatial-surface-chart/connect-spatial-surface-chart.js';
+export { connectSpatialTreemap, } from './connect-spatial-treemap/connect-spatial-treemap.js';

package/dist/three/bar-driver.d.ts

@@ -0,0 +1,35 @@
+import type { SpatialBarChartDriver } from '../connect-spatial-bar-chart/connect-spatial-bar-chart.js';
+/** How the three.js bar driver behaves where the page does not say. */
+export interface ThreeBarDriverOptions {
+    /**
+     * How many pixels the drawing has for each of the page's. By default, on a
+     * screen worked with a mouse, half as many again as the screen has, at
+     * least two and at most three; on a touch screen, as many as the screen
+     * has, at most two.
+     */
+    density?: number | undefined;
+}
+/**
+ * Draws a Spatial Bar Chart's bars in three dimensions with three.js. Pass it
+ * to `connectSpatialBarChart` with the element to draw in, which the chart
+ * holds in its plot:
+ *
+ * ```js
+ * import { connectSpatialBarChart } from '@fusion.dev/helix-plot'
+ * import { threeBarDriver } from '@fusion.dev/helix-plot/three'
+ *
+ * connectSpatialBarChart(chart, threeBarDriver(chart.querySelector('div')))
+ * ```
+ *
+ * **Each bar is a block from zero to its value**, on a grid of categories
+ * across and series in depth, in a box with a grid on its floor and two of
+ * its walls, lit from above. Each series takes a series color from the theme.
+ *
+ * **Dragging turns the box, and the wheel and a pinch bring it nearer.**
+ * Shift with an arrow on the chart turns it a step. It never turns by itself.
+ * It draws only while something moves, asks for no frames at rest, and
+ * shares the page's WebGL contexts with every three.js drawing Helix makes.
+ *
+ * The renderer is the driver's own, and `disconnect()` frees it.
+ */
+export declare const threeBarDriver: (container: HTMLElement, options?: ThreeBarDriverOptions) => SpatialBarChartDriver;

package/dist/three/bar-driver.js

@@ -0,0 +1,104 @@
+import { Box3, BoxGeometry, BufferGeometry, Color, DirectionalLight, EdgesGeometry, Float32BufferAttribute, HemisphereLight, LineBasicMaterial, LineSegments, Mesh, MeshLambertMaterial, Vector3, } from 'three';
+import { mergeGeometries } from 'three/addons/utils/BufferGeometryUtils.js';
+import { createStage, edgeOf, HALF, inBox, lookThrough } from './stage.js';
+const FOOTPRINT = 0.6;
+export const threeBarDriver = (container, options = {}) => {
+    let field;
+    let drawnCells = [];
+    let tops = new Map();
+    const barMaterial = new MeshLambertMaterial({
+        polygonOffset: true,
+        polygonOffsetFactor: 1,
+        polygonOffsetUnits: 1,
+        vertexColors: true,
+    });
+    const bars = new Mesh(new BufferGeometry(), barMaterial);
+    const edgeMaterial = new LineBasicMaterial({ vertexColors: true });
+    const edges = new LineSegments(new BufferGeometry(), edgeMaterial);
+    const stage = createStage(container, {
+        density: options.density,
+        pick: (ray) => {
+            const hit = ray.intersectObject(bars)[0];
+            if (hit?.faceIndex === undefined || hit.faceIndex === null) {
+                return -1;
+            }
+            return drawnCells[Math.floor(hit.faceIndex / 12)] ?? -1;
+        },
+    });
+    const sky = new HemisphereLight(0xffffff, 0xffffff, 2.2);
+    const sun = new DirectionalLight(0xffffff, 1);
+    sun.position.set(-2, 4, 1);
+    stage.scene.add(bars, edges, sky, sun);
+    const painted = (geometry, color) => {
+        const count = geometry.getAttribute('position').count;
+        const colors = new Float32Array(count * 3);
+        for (let at = 0; at < count; at++) {
+            colors.set([color.r, color.g, color.b], at * 3);
+        }
+        geometry.setAttribute('color', new Float32BufferAttribute(colors, 3));
+        return geometry;
+    };
+    return {
+        draw: (next, colors, font) => {
+            field = next;
+            const [ex, ey, ez] = next.axes.extent ?? [1, 1, 1];
+            const spacing = Math.min((2 * HALF * ex) / Math.max(next.categories.length, 1), (2 * HALF * ez) / Math.max(next.series.length, 1));
+            const width = spacing * FOOTPRINT;
+            const zero = inBox(next.axes.y, 0) * ey;
+            const page = new Color(colors.page);
+            const { emphasis, through } = colors.look;
+            const solids = [];
+            const lines = [];
+            drawnCells = [];
+            tops = new Map();
+            next.cells.forEach((cell, index) => {
+                if (cell.value === undefined) {
+                    return;
+                }
+                const tone = new Color(colors.groups[cell.depth % colors.groups.length] ?? colors.ink);
+                const color = emphasis === 'outlined' ? tone.clone().lerp(page, 0.4) : tone;
+                const top = inBox(next.axes.y, cell.value) * ey;
+                const tall = Math.max(Math.abs(top - zero), 1e-3);
+                const x = inBox(next.axes.x, cell.across) * ex;
+                const z = inBox(next.axes.z, cell.depth) * ez;
+                const box = new BoxGeometry(width, tall, width);
+                box.translate(x, Math.min(top, zero) + tall / 2, z);
+                solids.push(painted(box, color));
+                lines.push(painted(new EdgesGeometry(box), emphasis === 'solid' ? edgeOf(color) : tone));
+                drawnCells.push(index);
+                tops.set(index, new Vector3(x, Math.max(top, zero), z));
+            });
+            lookThrough(barMaterial, (emphasis === 'subtle' ? 0.2 : 1) * through);
+            lookThrough(edgeMaterial, through);
+            bars.geometry.dispose();
+            edges.geometry.dispose();
+            bars.geometry = (solids.length > 0 && mergeGeometries(solids)) || new BufferGeometry();
+            edges.geometry = (lines.length > 0 && mergeGeometries(lines)) || new BufferGeometry();
+            for (const one of [...solids, ...lines]) {
+                one.dispose();
+            }
+            stage.setAxes(next.axes, colors, font);
+            if (colors.look.box || tops.size === 0) {
+                stage.frame(new Vector3(-HALF * ex, -HALF * ey, -HALF * ez), new Vector3(HALF * ex, HALF * ey, HALF * ez));
+            }
+            else {
+                const around = new Box3().setFromBufferAttribute(bars.geometry.getAttribute('position'));
+                stage.frame(around.min, around.max);
+            }
+        },
+        focus: (index) => {
+            stage.setMarker(field ? tops.get(index) : undefined);
+        },
+        onHover: (listener) => stage.onHover(listener),
+        onPlace: (listener) => stage.onPlace(listener),
+        onPress: (listener) => stage.onPress(listener),
+        stop: () => {
+            bars.geometry.dispose();
+            barMaterial.dispose();
+            edges.geometry.dispose();
+            edgeMaterial.dispose();
+            stage.stop();
+        },
+        turnBy: (across, up, animate) => stage.turnBy(across, up, animate),
+    };
+};

package/dist/three/heatmap-driver.js

@@ -1,17 +1,12 @@
 import { BoxGeometry, BufferGeometry, Color, DirectionalLight, EdgesGeometry, Float32BufferAttribute, HemisphereLight, LineBasicMaterial, LineSegments, Mesh, MeshLambertMaterial, Vector3, } from 'three';
 import { mergeGeometries } from 'three/addons/utils/BufferGeometryUtils.js';
-import { createStage } from './stage.js';
+import { createStage, edgeOf, lookThrough } from './stage.js';
 const FOOTPRINT = 0.84;
 const MARGIN = 0.3;
 const THICKNESS = 0.25;
 const TILE = 0.05;
 const FLOOR = -0.3;
 const SPAN = 1.9;
-const edgeOf = (face) => {
-    const hsl = { h: 0, l: 0, s: 0 };
-    face.getHSL(hsl);
-    return face.clone().lerp(new Color(hsl.l < 0.5 ? 0xffffff : 0x000000), hsl.l < 0.5 ? 0.22 : 0.18);
-};
 export const threeHeatmapDriver = (container, options = {}) => {
     let field;
     let framed = false;
@@ -57,19 +52,25 @@ export const threeHeatmapDriver = (container, options = {}) => {
             field = next;
             const unit = SPAN / Math.max(next.columns, next.rows, 1);
             const tile = new Color(colors.extra.tile ?? colors.ground);
+            const page = new Color(colors.page);
+            const { emphasis, through } = colors.look;
             const solids = [];
             const lines = [];
             tops = next.cells.map((cell) => {
-                const color = cell.tone ? new Color(colors.extra[`tone-${cell.tone}`] ?? colors.ink) : tile;
+                const tone = cell.tone ? new Color(colors.extra[`tone-${cell.tone}`] ?? colors.ink) : tile;
+                const color = emphasis === 'outlined' ? tone.clone().lerp(page, 0.4) : tone;
                 const tall = Math.max(cell.height, TILE) * unit;
                 const x = (cell.column + 0.5 - next.columns / 2) * unit;
                 const z = (cell.row + 0.5 - next.rows / 2) * unit;
                 const box = new BoxGeometry(unit * FOOTPRINT, tall, unit * FOOTPRINT);
                 box.translate(x, FLOOR + tall / 2, z);
                 solids.push(painted(box, color));
-                lines.push(painted(new EdgesGeometry(box), edgeOf(color)));
+                lines.push(painted(new EdgesGeometry(box), emphasis === 'solid' ? edgeOf(color) : tone));
                 return new Vector3(x, FLOOR + tall, z);
             });
+            const area = emphasis === 'subtle' ? 0.2 : 1;
+            lookThrough(prismMaterial, area * through);
+            lookThrough(edgeMaterial, through);
             prisms.geometry.dispose();
             edges.geometry.dispose();
             prisms.geometry = (solids.length > 0 && mergeGeometries(solids)) || new BufferGeometry();

package/dist/three/index.d.ts

@@ -1,3 +1,6 @@
+export { type ThreeBarDriverOptions, threeBarDriver } from './bar-driver.js';
 export { type ThreeHeatmapDriverOptions, threeHeatmapDriver } from './heatmap-driver.js';
+export { type ThreeRibbonDriverOptions, threeRibbonDriver } from './ribbon-driver.js';
 export { type ThreeScatterDriverOptions, threeScatterDriver } from './scatter-driver.js';
 export { type ThreeSurfaceDriverOptions, threeSurfaceDriver } from './surface-driver.js';
+export { type ThreeTreemapDriverOptions, threeTreemapDriver } from './treemap-driver.js';

package/dist/three/index.js

@@ -1,3 +1,6 @@
+export { threeBarDriver } from './bar-driver.js';
 export { threeHeatmapDriver } from './heatmap-driver.js';
+export { threeRibbonDriver } from './ribbon-driver.js';
 export { threeScatterDriver } from './scatter-driver.js';
 export { threeSurfaceDriver } from './surface-driver.js';
+export { threeTreemapDriver } from './treemap-driver.js';