@fundar/data-chart-telling 1.15.0 → 1.17.0

package/examples/datasets/economic-activity.ts

@@ -0,0 +1,40 @@
+// ── The weight of each branch of activity in a city's gross added value ──────
+// IDECBA, value added at basic prices by branch of activity, Ciudad de Buenos Aires,
+// 2024 (preliminary), in millions of pesos of 2004. A selection of the larger branches.
+
+export type ActivityRow = {
+	sector: 'Primary' | 'Secondary' | 'Tertiary';
+	kind: string;
+	branch: string;
+	/** Millions of pesos of 2004. */
+	value: number;
+};
+
+export const ACTIVITY_BRANCHES: ActivityRow[] = [
+	{ sector: 'Primary', kind: 'Extraction', branch: 'Oil, gas and coal', value: 778 },
+	{ sector: 'Primary', kind: 'Agriculture', branch: 'Agriculture and livestock', value: 193 },
+	{ sector: 'Secondary', kind: 'Manufacturing', branch: 'Chemicals', value: 2999 },
+	{ sector: 'Secondary', kind: 'Manufacturing', branch: 'Food and beverages', value: 2882 },
+	{ sector: 'Secondary', kind: 'Manufacturing', branch: 'Publishing and printing', value: 1251 },
+	{ sector: 'Secondary', kind: 'Manufacturing', branch: 'Machinery and equipment', value: 973 },
+	{ sector: 'Secondary', kind: 'Manufacturing', branch: 'Clothing', value: 814 },
+	{ sector: 'Secondary', kind: 'Manufacturing', branch: 'Textiles', value: 381 },
+	{
+		sector: 'Tertiary',
+		kind: 'Trade and transport',
+		branch: 'Wholesale and retail trade',
+		value: 15365
+	},
+	{ sector: 'Tertiary', kind: 'Trade and transport', branch: 'Transport', value: 3707 },
+	{ sector: 'Tertiary', kind: 'Trade and transport', branch: 'Communications', value: 8210 },
+	{ sector: 'Tertiary', kind: 'Finance', branch: 'Banking and finance', value: 7857 },
+	{ sector: 'Tertiary', kind: 'Finance', branch: 'Insurance', value: 3106 },
+	{ sector: 'Tertiary', kind: 'Public services', branch: 'Public administration', value: 7606 },
+	{ sector: 'Tertiary', kind: 'Public services', branch: 'Public education', value: 2374 },
+	{ sector: 'Tertiary', kind: 'Public services', branch: 'Public health', value: 1525 },
+	{ sector: 'Tertiary', kind: 'Private services', branch: 'Private health', value: 5439 },
+	{ sector: 'Tertiary', kind: 'Private services', branch: 'Private education', value: 1952 },
+	{ sector: 'Tertiary', kind: 'Private services', branch: 'Restaurants and bars', value: 2439 },
+	{ sector: 'Tertiary', kind: 'Real estate', branch: 'Housing', value: 6179 },
+	{ sector: 'Tertiary', kind: 'Real estate', branch: 'Construction', value: 3905 }
+];

package/examples/datasets/index.ts

@@ -5,6 +5,7 @@ export * from './commodity-prices';
 export * from './countries-over-time';
 export * from './daily-temperature';
 export * from './earthquakes';
+export * from './economic-activity';
 export * from './flight-routes';
 export * from './height-density';
 export * from './heights';

package/llms-full.txt

@@ -12,7 +12,7 @@ Svelte 5 plot components on top of svelteplot. This file is checked against the
 ## The mental model
 
 - A **plot** is one graph (axes + marks). Titles, subtitle, caption, legend, facets and a timeline are props of the plot itself.
-- Plots: `LinePlot AreaPlot BarPlot DensityPlot HistogramPlot BoxPlot ViolinPlot LollipopPlot DumbbellPlot ClevelandPlot ForestPlot BulletPlot SlopePlot SparklinePlot HeatmapPlot PyramidPlot ScatterPlot GeoPlot`.
+- Plots: `LinePlot AreaPlot BarPlot DensityPlot HistogramPlot BoxPlot ViolinPlot LollipopPlot DumbbellPlot ClevelandPlot ForestPlot BulletPlot SlopePlot SparklinePlot TreemapPlot HeatmapPlot PyramidPlot ScatterPlot GeoPlot`.
 - `PlotComposer` lays several plots out in one figure with shared hover, legend and timeline.
 - `width` and `height` are pixel numbers on a standalone plot. To fill a container or the window, bind its size (`examples/ResponsiveLine.svelte`) and render the plot once both are > 0.
 
@@ -43,12 +43,12 @@ Two ways to give data, one per plot:
 | `segments` | Style ranges of the data (rule 1 below). |
 | `markers` | Extra marks, an array of `{ type: '...', ... }`. |
 | `margins` | `{ top, right, bottom, left }`, each a number or `'auto'` (all `'auto'` by default). |
-| `tooltip` | `true` or `{ strategy, sync, format, content, series, anchorX, anchorY }`. The text lists matched rows highest value first; a `content` snippet gets them unsorted. |
+| `tooltip` | `true` or `{ strategy, sync, format, content, series, anchorX, anchorY }`; `format(row, number, context)`, `context` holding the row's `series` and what the kind adds (a treemap's `share`). The text lists matched rows highest value first; a `content` snippet gets them unsorted. |
 | `timeline` | `{ accessor: 'year' }` steps through the rows by a field, drawn as a player bar (default); `type: 'rule'` draws a rule beside the plot instead. The field may hold numbers, `Date`s or date strings (ISO, or any other with `dateFormat: 'DD/MM/YYYY'`); date steps read as dates, and reach `onvalue`, `player.format` and `useFigure().timeline` (`steps`, `value`, `seekValue`) as `Date`s. Other options: `progress` (position, `0`-`1`), `values` (the steps, when not every distinct value), `filterMode` (`'exact'` shows the current step's rows, `'upTo'` every row up to it; `LinePlot` defaults to `'upTo'`), `interpolate` (tween values between steps), `scales` (`'shared'` keeps both axes still across steps, `'free'` refits both to each step, `'free-x'`/`'free-y'` refit one and keep the other still), `onprogress`, `onvalue`, and a rule's `orientation`, `show` and `thickness`. |
 | `facet` | `{ by: 'field', columns, gap, scales: 'shared'\|'free'\|'free-x'\|'free-y', mode: 'grid'\|'carousel'\|'paginated' }` or `{ rows, cols }`. |
-| `transforms` `statistics` | svelteplot transforms / derived summaries. `statistics` is `[{ type, ...options, series?, pooled? }]` (per series by default, `series: ['a']` only those, `pooled: true` all rows at once; a marker's own `.statistics` runs over its own `data`). Types: `regression` (`regressionType`: `'linear'|'quad'|'poly'|'exp'|'log'|'pow'|'loess'`, `order`, `base`, `span`, `confidence`, `styles`), `movingAverage` (`k`, `reduce`, `styles`), `bollinger` (`n`, `k`, `styles`), `density` (`kernel`, `bandwidth`, `styles`), `density2d` (`bandwidth`, `thresholds`, `styles`), `box` (the `box` marker's options), `deviation` (a rule at an estimator and a band around it, along the plot's value axis: `estimator`: `'mean'|'median'|'midrange'`, `spread`: `'stdev'|'mad'`, `k`, `rule` and `band`: styles or `false`, each with an optional `label: true | { text, styles: FontStyle }`, the band's also `edge: 'lower'|'upper'` and `position: 'inside'|'outside'`)|'upper'`). |
+| `transforms` `statistics` | svelteplot transforms / derived summaries. `treemap` is the library's own transform: `{ type: 'treemap', value: 'count', levels: ['island', 'species'], tile: 'squarify', aspect: 1 }` makes a tile per distinct path of `levels` (outermost first), its area the sum of its rows' `value`, and gives a `rect` marker `x1`/`x2`/`y1`/`y2` in the unit square (`x`/`y` at each tile's centre for a `text`). `statistics` is `[{ type, ...options, series?, pooled? }]` (per series by default, `series: ['a']` only those, `pooled: true` all rows at once; a marker's own `.statistics` runs over its own `data`). Types: `regression` (`regressionType`: `'linear'|'quad'|'poly'|'exp'|'log'|'pow'|'loess'`, `order`, `base`, `span`, `confidence`, `styles`), `movingAverage` (`k`, `reduce`, `styles`), `bollinger` (`n`, `k`, `styles`), `density` (`kernel`, `bandwidth`, `styles`), `density2d` (`bandwidth`, `thresholds`, `styles`), `box` (the `box` marker's options), `deviation` (a rule at an estimator and a band around it, along the plot's value axis: `estimator`: `'mean'|'median'|'midrange'`, `spread`: `'stdev'|'mad'`, `k`, `rule` and `band`: styles or `false`, each with an optional `label: true | { text, styles: FontStyle }`, the band's also `edge: 'lower'|'upper'` and `position: 'inside'|'outside'`)|'upper'`). |
 
-Per kind: `BarPlot` x = category, y = value (swap for horizontal bars); `PyramidPlot` mirrors two series around zero; `HeatmapPlot` colors cells by `color`; `HistogramPlot` bins one numeric field; `DensityPlot` smooths one numeric field into a kernel density curve (`styles.mark: 'line'` draws a line instead of an area; a `densityX` transform sets `kernel` and `bandwidth`); `BoxPlot` x = category, y = value, one box per category (its tooltip row is the box summary: `min`, `p25`, `median`, `p75`, `max`, `count`, `outliers`); `ViolinPlot` x = category, y = value (swap for horizontal), the mirrored density of each category's values with a box inside (`styles`: `kernel`, `bandwidth`, `trim`, `scale: 'width'|'shared'`, `box: false | width`; its tooltip row is a box plot's); `LollipopPlot` x = category, y = value, one dot on a stem per category (stems start at zero, or at the nearest end of a pinned domain; `styles.values` labels each dot); `DumbbellPlot` x = category, y = value, `color`/`grouping` names exactly two series, joined by a connector per category (another count warns); `ClevelandPlot` is the same for any number of series, joined from the lowest to the highest (use `grouping` for a numeric series field; `styles.values.select` (`'first'|'last'|'min'|'max'` or a list), `series` and `color: 'series'` choose and color the labelled dots; `styles.connector` sets the connector's `width` (number or `'dots'` for a band), `color` (one, `{ by: 'sign' | 'difference' | 'length' }` or a function), `opacity`, `arrow` (draws the from-to stretch as an arrow), `outside` (the part past the from/to dots), `label` (centered on the from-to stretch) and the `from`/`to` series of its difference); `ForestPlot` x = value, y = category (or swapped), one dot per row on a stem spanning its interval given by `lower`/`upper` fields or an `error` either side (the value axis fits the intervals; `styles.connector.caps` toggles the end ticks, on by default); `BulletPlot` is a bar plot with a `target` (field, function or number: a tick across the band) and `ranges` (upper bounds, each a field, function or number: bands from the baseline, the smallest darkest) drawn around its thin bars (the value axis reaches them); `SlopePlot` x = category (its first and last positions are the two moments), y = value, a line with a dot on every point per series, its first and last labelled before and after it by `styles.values` (the value axis is hidden by default; `scales.y.axisDisplay: 'visible'` shows it); `SparklinePlot` is a small `LinePlot` with no axes and no legend (`legend` and `margins` bring them back), a dot on each series' last point and its value beside it (`styles.values` formats it or turns it off with `show: false`; `facet` makes one per category); `ScatterPlot` takes `r` (size) and `symbol`; `GeoPlot` takes GeoJSON/TopoJSON in `data` and `coordinates` for the projection (`docs/geo.md`).
+Per kind: `BarPlot` x = category, y = value (swap for horizontal bars); `PyramidPlot` mirrors two series around zero; `HeatmapPlot` colors cells by `color`; `HistogramPlot` bins one numeric field; `DensityPlot` smooths one numeric field into a kernel density curve (`styles.mark: 'line'` draws a line instead of an area; a `densityX` transform sets `kernel` and `bandwidth`); `BoxPlot` x = category, y = value, one box per category (its tooltip row is the box summary: `min`, `p25`, `median`, `p75`, `max`, `count`, `outliers`); `ViolinPlot` x = category, y = value (swap for horizontal), the mirrored density of each category's values with a box inside (`styles`: `kernel`, `bandwidth`, `trim`, `scale: 'width'|'shared'`, `box: false | width`; its tooltip row is a box plot's); `LollipopPlot` x = category, y = value, one dot on a stem per category (stems start at zero, or at the nearest end of a pinned domain; `styles.values` labels each dot); `DumbbellPlot` x = category, y = value, `color`/`grouping` names exactly two series, joined by a connector per category (another count warns); `ClevelandPlot` is the same for any number of series, joined from the lowest to the highest (use `grouping` for a numeric series field; `styles.values.select` (`'first'|'last'|'min'|'max'` or a list), `series` and `color: 'series'` choose and color the labelled dots; `styles.connector` sets the connector's `width` (number or `'dots'` for a band), `color` (one, `{ by: 'sign' | 'difference' | 'length' }` or a function), `opacity`, `arrow` (draws the from-to stretch as an arrow), `outside` (the part past the from/to dots), `label` (centered on the from-to stretch) and the `from`/`to` series of its difference); `ForestPlot` x = value, y = category (or swapped), one dot per row on a stem spanning its interval given by `lower`/`upper` fields or an `error` either side (the value axis fits the intervals; `styles.connector.caps` toggles the end ticks, on by default); `BulletPlot` is a bar plot with a `target` (field, function or number: a tick across the band) and `ranges` (upper bounds, each a field, function or number: bands from the baseline, the smallest darkest) drawn around its thin bars (the value axis reaches them); `SlopePlot` x = category (its first and last positions are the two moments), y = value, a line with a dot on every point per series, its first and last labelled before and after it by `styles.values` (the value axis is hidden by default; `scales.y.axisDisplay: 'visible'` shows it); `SparklinePlot` is a small `LinePlot` with no axes and no legend (`legend` and `margins` bring them back), a dot on each series' last point and its value beside it (`styles.values` formats it or turns it off with `show: false`; `facet` makes one per category); `TreemapPlot` takes `value` (a tile's area) and `grouping` (the whole path of a tile, fields joined by dots, outermost first: `'sector.branch'` - the last level names it, rows with one path are one tile, the outermost colors the tiles and the legend); a `treemap` entry in its `transforms` sets `tile` (`'squarify'` default, `'binary'`, `'slice'`, `'dice'`, `'sliceDice'`); its tiles are labelled by `styles.values` with their name over their share of the whole, cut short or reduced to the share alone where they do not fit; its `segments` can be keyed by the path of a tile (`'Tertiary.Finance'`) and `tooltip.format(row, number, context)` gets the tile's row and a `context` with its `series` and `share` (0-100); `ScatterPlot` takes `r` (size) and `symbol`; `GeoPlot` takes GeoJSON/TopoJSON in `data` and `coordinates` for the projection (`docs/geo.md`).
 
 ## Switches
 
@@ -77,7 +77,7 @@ Inside a plot's snippets (`header`, `footer`, tooltip `content`) or any child of
 
 - `useFigure()` returns `{ hover, legend, timeline }` for the whole figure.
 - `usePlot()` returns the same plus `margins`, `scales`, `axes`, `data`, `width`, `height`, `svelteplot` (inside a plot, e.g. a `component` marker).
-- `legend.off` (names of hidden series), `legend.isOff(name)`, `legend.toggle(name, action)`, `turnOff`, `turnOn`. `action` is `{ mode: 'dim' | 'hide' | 'omit' }`; `'omit'` removes the series and refits the axes, so the visible domain follows `legend.off`.
+- `legend.off` (names of hidden series), `legend.isOff(name)`, `legend.toggle(name, action)`, `turnOff`, `turnOn`. `action` is `{ mode: 'dim' | 'hide' | 'omit' | 'rescale' }`; `'omit'` removes the series and refits the axes, and `'rescale'` also makes the parts left of a whole (a stack, a treemap) the new 100%, so the visible domain follows `legend.off`.
 - `timeline.steps`, `value`, `progress`, `playing`, `seek(p)`, `seekValue(v)`, `next()`, `previous()`, `play()`, `pause()`, `toggle()`, `setSpeed()`.
 - `hover.activeX`, `activeY`, `activeSeries`, `source`.
 

package/llms.txt

@@ -26,6 +26,7 @@ Start with the full guide: it lists the mental model, the props every plot share
   - [BulletPlot](./docs/plots/ranking/bullet.md)
   - [SlopePlot](./docs/plots/evolution/slope.md)
   - [SparklinePlot](./docs/plots/evolution/sparkline.md)
+  - [TreemapPlot](./docs/plots/part-of-a-whole/treemap.md)
   - [ClevelandPlot](./docs/plots/ranking/cleveland.md)
   - [HeatmapPlot](./docs/plots/correlation/heatmap.md)
   - [PyramidPlot](./docs/plots/distribution/pyramid.md)
@@ -55,6 +56,7 @@ Start with the full guide: it lists the mental model, the props every plot share
 - [Timeline rule driven by a slider](./examples/TimelineRule.svelte)
 - [Facets with a synced tooltip](./examples/Facets.svelte)
 - [Bars with value labels](./examples/BarValues.svelte)
+- [Treemap: a tile per row, sized by its value and nested by grouping](./examples/Treemap.svelte)
 - [Custom tooltip card](./examples/CustomTooltip.svelte)
 - [The smallest plot: rows, fields and a pixel size](./examples/FirstPlot.svelte)
 - [Line per series over a date axis, with end labels](./examples/LineDates.svelte)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fundar/data-chart-telling",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "Declarative charts, maps and small multiples for Svelte, built on svelteplot.",
   "license": "MIT",
   "author": "Ezequiel Puerta",
@@ -53,6 +53,7 @@
     "@types/geojson": "^7946.0.16",
     "d3-array": "^3.2.4",
     "d3-geo": "^3.1.1",
+    "d3-hierarchy": "^3.1.3",
     "d3-interpolate": "^3.0.1",
     "d3-scale-chromatic": "^3.1.0",
     "d3-selection": "^3.0.0",
@@ -81,6 +82,7 @@
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
     "@types/d3-array": "^3.2.2",
     "@types/d3-geo": "^3.1.0",
+    "@types/d3-hierarchy": "^3.1.7",
     "@types/d3-interpolate": "^3.0.4",
     "@types/d3-scale-chromatic": "^3.1.0",
     "@types/d3-selection": "^3.0.11",