@fundar/data-chart-telling 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.2.0] - 2026-10-24
+
+### Added
+
+- `LollipopPlot`, a dot on a stem for the value of each category.
+- `DumbbellPlot`, two series joined by a connector for each category.
+- `ClevelandPlot`, any number of series per category joined from the lowest to the highest value, with connectors you can color, turn into arrows and sort by series value or range.
+- `ForestPlot`, a dot per row on a stem spanning its confidence interval.
+- `BulletPlot`, a bar against a target tick and shaded qualitative ranges.
+- `SlopePlot`, the change of each series between two moments, labelled at both ends.
+- `SparklinePlot`, a small axisless line with a dot and a label on its last point.
+- `DensityPlot`, a kernel density curve of one numeric field, and `ViolinPlot`, the mirrored density of each category with a box inside.
+- Step lines through `styles.curve: 'step'`, `'step-after'` or `'step-before'` on `LinePlot`.
+- A `deviation` statistic that draws an estimator of the values and a band around it, with optional labels.
+- `styles.values.select` chooses which points get a value label (`'first'`, `'last'`, `'min'`, `'max'` or a list), for line, area and Cleveland-family plots.
+- The size channel (`r`) works on the dots of the Cleveland family, and its automatic legend is configured under the `r` key.
+- Every marker takes `dx` and `dy` to move it a number of pixels, on a map too, and `dot`, `text` and `image` markers also take a function of the row to move each row on its own.
+- `setConfiguration({ palette })` takes the name of a d3-scale-chromatic scheme (`'viridis'`, `'dark2'`...) or `{ scheme, count, schemeRange }` instead of just a list of colors.
+- `continuous.scheme` and `continuous.schemeRange` in the configuration set the default continuous ramp by the name of a d3-scale-chromatic ramp, as an alternative to its `min` and `max` colors.
+- Tick labels turn or thin out on small plots when they would not fit, and the last label of an axis that is not rounded to nice values stays inside the plot.
+- A timeline can free one axis at a time (`scales: 'free-x'` or `'free-y'`) while the other keeps its shared domain.
+- `link` markers on a map can lift their arcs off the surface (`altitude`) and cut them where a globe hides them (`occlusion`).
+
+### Changed
+
+- The default palette is Tableau 10, and the default continuous ramp, the timeline and player accents and the connector colors follow it.
+
+### Fixed
+
+- The example datasets moved out of the stories into `examples/datasets`, where real data replaces the synthetic rows and the docs, examples and stories all read the same files.
+- The Minard map of Napoleon's march is rebuilt with `GeoPlot` and `LinePlot` markers instead of a hand-assembled svelteplot chart.
+
 ## [1.1.0] - 2026-10-20
 
 ### Added

package/README.md

@@ -23,7 +23,7 @@ It aims for a sweet spot between the flexibility of `d3`, the declarative spirit
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { REGION_VALUES } from './data';
+	import { REGION_VALUES } from './datasets';
 </script>
 
 <!-- One line per region, with a title, the automatic legend, end-of-line values and a tooltip. -->
@@ -45,9 +45,9 @@ It aims for a sweet spot between the flexibility of `d3`, the declarative spirit
 
 ![A line plot with a title, a legend, end-of-line value labels and a tooltip](docs/images/line-by-region.png)
 
-Every Svelte snippet in this README is a runnable file in [examples/](examples/), and the data comes from [examples/data.ts](examples/data.ts).
+Every Svelte snippet in this README is a runnable file in [examples/](examples/), and the data comes from [examples/datasets/](examples/datasets/).
 
-Nine plot kinds - line, area, bar, histogram, box, heatmap, pyramid, scatter and geographic maps - share one vocabulary: the same channels (`x`, `y`, `color`, `grouping`, `opacity`, `symbol`, `r`), the same `scales`, `styles`, `segments`, `markers`, `transforms`, `tooltip`, `legend`, `timeline` and `facet` props, and one global theme.
+Every plot kind shares one vocabulary: the same channels (`x`, `y`, `color`, `grouping`, `opacity`, `symbol`, `r`), the same `scales`, `styles`, `segments`, `markers`, `transforms`, `tooltip`, `legend`, `timeline` and `facet` props, and one global theme.
 
 ## Install
 
@@ -68,7 +68,7 @@ The package ships Svelte components, so the app needs the Svelte compiler (`@sve
 ```svelte
 <script lang="ts">
 	import { BarPlot } from '@fundar/data-chart-telling';
-	import { REGION_VALUES } from './data';
+	import { REGION_VALUES } from './datasets';
 </script>
 
 <!--
@@ -100,7 +100,7 @@ The package ships Svelte components, so the app needs the Svelte compiler (`@sve
 ```svelte
 <script lang="ts">
 	import { LinePlot } from '@fundar/data-chart-telling';
-	import { REGION_VALUES } from './data';
+	import { REGION_VALUES } from './datasets';
 
 	// A rule has no controls of its own: the page moves it through `progress` (0 to 1).
 	// One step per year; a line plot shows every row up to the current step.
@@ -133,7 +133,7 @@ Start with the concepts; the rest is organised by what you want a plot to do.
 | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
 | [Getting started](docs/getting-started.md)                     | Installing, a first plot, sizing a plot to its container, loading data                       |
 | [Concepts](docs/concepts.md)                                   | Plots and figures, rows and series, channels, the props every plot shares                    |
-| [Plots](docs/plots.md)                                         | The eight plot kinds: what each one draws and what it needs                                  |
+| [Plots](docs/plots.md)                                         | Every plot kind: what it draws and what it needs                                             |
 | [Scales](docs/scales.md)                                       | Axes (`x`, `y`) and channel scales (`color`, `grouping`, `opacity`, `symbol`, `r`, `length`) |
 | [Styles and segments](docs/styles-and-segments.md)             | Value labels, frames, gap filling, and styling ranges of the data                            |
 | [Markers](docs/markers.md)                                     | Extra marks on a plot: annotations, regions, hover highlights, custom components             |

package/dist/configuration/config.svelte.d.ts

@@ -2,7 +2,7 @@ import type { PlotStylesConfig, PlotStylesConfigInput } from '../types/configura
 export declare const DEFAULT_CONFIG: PlotStylesConfig;
 /** Read the live, reactive configuration. */
 export declare function getConfiguration(): PlotStylesConfig;
-/** Deep-merge a partial override into the global configuration. Reactive. */
+/** Deep-merge a partial override into the global configuration - a `palette` may be a scheme name. Reactive. */
 export declare function setConfiguration(patch: PlotStylesConfigInput): PlotStylesConfig;
 /** Restore the shipped defaults. */
 export declare function resetConfiguration(): void;

package/dist/configuration/config.svelte.js

@@ -1,4 +1,5 @@
 import { merge } from '../utils/merge';
+import { Palette } from '../utils/color';
 /**
  * Global, reactive styling configuration. Chrome reads it as CSS custom
  * properties ({@link configToCssVars}); plots read it as plain values.
@@ -16,9 +17,17 @@ const text = (over) => ({
     ...over
 });
 export const DEFAULT_CONFIG = {
+    // ── General look ────────────────────────────────────────────────────────────
     font: 'inherit',
     color: 'currentColor',
     background: 'transparent',
+    title: text({ size: '1.5rem', weight: 500, leading: '1.2' }),
+    subtitle: text({
+        size: '1rem',
+        weight: 400,
+        color: 'color-mix(in srgb, currentColor 85%, transparent)'
+    }),
+    caption: text({ size: '0.75rem', color: 'color-mix(in srgb, currentColor 75%, transparent)' }),
     spacing: {
         headerPadding: '0.5rem 0',
         legendPadding: '0.5rem 0',
@@ -48,13 +57,32 @@ export const DEFAULT_CONFIG = {
         ],
         rowGap: '1rem'
     },
-    title: text({ size: '1.5rem', weight: 500, leading: '1.2' }),
-    subtitle: text({
-        size: '1rem',
-        weight: 400,
-        color: 'color-mix(in srgb, currentColor 85%, transparent)'
-    }),
-    caption: text({ size: '0.75rem', color: 'color-mix(in srgb, currentColor 75%, transparent)' }),
+    // Tableau 10 - qualitative, with a muted blue first, and distinct enough to tell ten series apart.
+    palette: Palette.resolve('tableau10'),
+    symbols: ['circle', 'square', 'triangle', 'diamond', 'star', 'cross'],
+    // A light tint of the palette's first color up to the color itself.
+    continuous: { min: '#eaf0f6', max: '#4e79a7', labelColor: '#111827', opacityRange: [0.2, 1] },
+    margins: { top: 'auto', right: 'auto', bottom: 'auto', left: 'auto' },
+    frameClip: { tolerance: 2 },
+    // ── Features ────────────────────────────────────────────────────────────────
+    axis: {
+        color: 'currentColor',
+        fontSize: 14,
+        labelFontSize: 14,
+        titleFontSize: 14,
+        xTickSize: 5,
+        yTickSize: 5,
+        xTickPadding: 10,
+        yTickPadding: 10,
+        grid: false,
+        locale: 'es-AR',
+        compactDisplay: 'short',
+        edgeTicks: {
+            x: { enabled: true, collision: 'drop-nice' },
+            y: { enabled: false, collision: 'drop-nice' }
+        },
+        autoRotate: true
+    },
     legend: {
         font: 'inherit',
         size: '0.875rem',
@@ -79,6 +107,10 @@ export const DEFAULT_CONFIG = {
             height: 20,
             barHeight: 12,
             barRadius: 2,
+            opacity: {
+                color: '#000',
+                checker: { size: 4, light: '#fff', dark: '#d4d4d8' }
+            },
             // A slim vertical bar handle, taller than the 12px gradient track.
             handle: {
                 width: '6px',
@@ -105,23 +137,6 @@ export const DEFAULT_CONFIG = {
             }
         }
     },
-    axis: {
-        color: 'currentColor',
-        fontSize: 14,
-        labelFontSize: 14,
-        titleFontSize: 14,
-        xTickSize: 5,
-        yTickSize: 5,
-        xTickPadding: 10,
-        yTickPadding: 10,
-        grid: false,
-        locale: 'es-AR',
-        compactDisplay: 'short',
-        edgeTicks: {
-            x: { enabled: true, collision: 'drop-nice' },
-            y: { enabled: false, collision: 'drop-nice' }
-        }
-    },
     tooltip: {
         background: '#111827',
         color: '#ffffff',
@@ -130,42 +145,31 @@ export const DEFAULT_CONFIG = {
         radius: '0.375rem',
         border: 'none'
     },
-    margins: { top: 'auto', right: 'auto', bottom: 'auto', left: 'auto' },
-    frameClip: { tolerance: 5 },
-    // ColorBrewer Dark2 - qualitative, harmonious, and dark enough to read on white.
-    palette: ['#1b9e77', '#d95f02', '#7570b3', '#e7298a', '#66a61e', '#e6ab02', '#a6761d', '#666666'],
-    symbols: ['circle', 'square', 'triangle', 'diamond', 'star', 'cross'],
-    continuous: { min: '#f7fcfd', max: '#1b9e77', labelColor: '#111827', opacityRange: [0.2, 1] },
-    line: {
-        strokeWidth: 3,
-        dotRadius: 4,
-        gap: {
-            stroke: { strokeOpacity: 0.6, strokeDasharray: '4 4' },
-            dots: {}
-        }
+    hover: {
+        rule: { stroke: '#e6580d', strokeOpacity: 0.35, strokeWidth: 1.5, strokeDasharray: '4 4' },
+        dot: { dotRadius: 5, dotFill: 'currentColor' },
+        font: { fill: 'currentColor', fontSize: 12, dy: -18 },
+        area: { fill: '#94a3b8', fillOpacity: 0.4 }
     },
-    text: {
-        declutter: {
-            elbowGap: 10,
-            laneStep: 7,
-            labelGap: 6,
-            connector: { stroke: '#94a3b8', strokeWidth: 0.5 }
+    facet: {
+        indicator: {
+            background: '#111827',
+            color: '#ffffff',
+            fontSize: '0.8125rem',
+            padding: '0.125rem 0.5rem',
+            radius: '999px'
+        },
+        navButton: {
+            background: '#111827',
+            color: '#ffffff',
+            size: '2rem',
+            fontSize: '1.1rem',
+            disabledOpacity: 0.3
         }
     },
-    bar: {
-        gap: { fillOpacity: 0.5 },
-        seriesPadding: 0.2,
-        paddingInner: 0.15,
-        paddingOuter: 0.15
-    },
-    pyramid: { gap: { fillOpacity: 0.5 } },
-    area: { fillOpacity: 0.6 },
-    histogram: { inset: 1, fillOpacity: 1 },
-    box: { fillOpacity: 0.9, paddingInner: 0.4, paddingOuter: 0.2 },
-    scatter: { dotRadius: 5 },
     timeline: {
         axisColor: 'currentColor',
-        activeColor: '#1b9e77',
+        activeColor: '#4e79a7',
         thickness: 60,
         gap: '12px',
         rule: {
@@ -190,22 +194,22 @@ export const DEFAULT_CONFIG = {
             valueWidth: '3rem',
             button: {
                 size: '2rem',
-                background: '#1b9e77',
+                background: '#4e79a7',
                 color: '#ffffff',
-                hoverBackground: '#0c4937',
+                hoverBackground: '#24384d',
                 radius: '999px'
             },
             track: {
                 height: '3px',
                 color: 'color-mix(in srgb, currentColor 25%, transparent)',
-                fillColor: '#1b9e77',
+                fillColor: '#4e79a7',
                 radius: '999px'
             },
-            thumb: { size: '14px', color: '#1b9e77' },
+            thumb: { size: '14px', color: '#4e79a7' },
             toggle: {
                 background: 'transparent',
                 color: 'currentColor',
-                activeBackground: '#1b9e77',
+                activeBackground: '#4e79a7',
                 activeColor: '#ffffff',
                 radius: '0.375rem',
                 fontSize: '0.75rem',
@@ -213,11 +217,15 @@ export const DEFAULT_CONFIG = {
             }
         }
     },
-    hover: {
-        rule: { stroke: '#e6580d', strokeOpacity: 0.35, strokeWidth: 1.5, strokeDasharray: '4 4' },
-        dot: { dotRadius: 5, dotFill: 'currentColor' },
-        font: { fill: 'currentColor', fontSize: 12, dy: -18 },
-        area: { fill: '#94a3b8', fillOpacity: 0.25 }
+    connector: {
+        sign: { positive: '#59a14f', negative: '#e15759', zero: '#9ca3af' },
+        lengthScheme: ['#d1d5db', '#374151'],
+        differenceScheme: ['#e15759', '#e5e7eb', '#59a14f'],
+        arrow: { width: 2, headLength: 8, headAngle: 60 },
+        capLength: 8,
+        outsideOpacity: 0.4,
+        labelFontSize: 11,
+        labelGap: 4
     },
     // Beside a vertical delta (taken on x), above a horizontal one (on y).
     delta: {
@@ -226,22 +234,79 @@ export const DEFAULT_CONFIG = {
             y: { dx: 0, dy: -10, lineAnchor: 'middle', textAnchor: 'middle' }
         }
     },
-    facet: {
-        indicator: {
-            background: '#111827',
-            color: '#ffffff',
-            fontSize: '0.8125rem',
-            padding: '0.125rem 0.5rem',
-            radius: '999px'
-        },
-        navButton: {
-            background: '#111827',
-            color: '#ffffff',
-            size: '2rem',
-            fontSize: '1.1rem',
-            disabledOpacity: 0.3
+    text: {
+        declutter: {
+            elbowGap: 10,
+            laneStep: 7,
+            labelGap: 6,
+            connector: { stroke: '#94a3b8', strokeWidth: 0.5 }
+        }
+    },
+    // ── Plot kinds ──────────────────────────────────────────────────────────────
+    area: { fillOpacity: 0.6 },
+    bar: {
+        gap: { fillOpacity: 0.5 },
+        seriesPadding: 0.2,
+        paddingInner: 0.15,
+        paddingOuter: 0.15
+    },
+    box: { fillOpacity: 0.9, paddingInner: 0.4, paddingOuter: 0.2 },
+    bullet: {
+        barThickness: 10,
+        rangeWidth: 28,
+        rangeColors: ['#9ca3af', '#d1d5db', '#eceff3'],
+        targetLength: 22,
+        targetWidth: 3,
+        paddingInner: 0.4,
+        paddingOuter: 0.3
+    },
+    cleveland: {
+        dotRadius: 5,
+        stemWidth: 5,
+        connectorColor: '#9ca3af',
+        labelGap: 10,
+        paddingInner: 0.5,
+        paddingOuter: 0.5
+    },
+    density: { fillOpacity: 0.6, strokeWidth: 2 },
+    dumbbell: {
+        dotRadius: 6,
+        stemWidth: 'dots',
+        connectorColor: '#9ca3af',
+        labelGap: 10,
+        paddingInner: 0.5,
+        paddingOuter: 0.5
+    },
+    forest: {
+        dotRadius: 5,
+        stemWidth: 2,
+        caps: true,
+        labelGap: 10,
+        paddingInner: 0.5,
+        paddingOuter: 0.5
+    },
+    histogram: { inset: 1, fillOpacity: 1 },
+    line: {
+        curve: 'auto',
+        strokeWidth: 3,
+        dotRadius: 4,
+        gap: {
+            stroke: { strokeOpacity: 0.6, strokeDasharray: '4 4' },
+            dots: {}
         }
-    }
+    },
+    lollipop: {
+        dotRadius: 6,
+        stemWidth: 2,
+        labelGap: 10,
+        paddingInner: 0.5,
+        paddingOuter: 0.5
+    },
+    pyramid: { gap: { fillOpacity: 0.5 } },
+    scatter: { dotRadius: 5 },
+    slope: { strokeWidth: 2, dotRadius: 5, padding: 0 },
+    sparkline: { strokeWidth: 1.5, dotRadius: 3 },
+    violin: { fillOpacity: 0.6, paddingInner: 0.2, paddingOuter: 0.2, boxWidth: 8 }
 };
 // ── Reactive store ──────────────────────────────────────────────────────────
 let current = $state(structuredClone(DEFAULT_CONFIG));
@@ -249,9 +314,9 @@ let current = $state(structuredClone(DEFAULT_CONFIG));
 export function getConfiguration() {
     return current;
 }
-/** Deep-merge a partial override into the global configuration. Reactive. */
+/** Deep-merge a partial override into the global configuration - a `palette` may be a scheme name. Reactive. */
 export function setConfiguration(patch) {
-    current = merge(current, patch);
+    current = merge(current, Palette.resolveIn(patch));
     return current;
 }
 /** Restore the shipped defaults. */
@@ -273,6 +338,9 @@ export function configToCssVars(c) {
         '--dct-font': c.font,
         '--dct-fg': c.color,
         '--dct-bg': c.background,
+        ...t('title', c.title),
+        ...t('subtitle', c.subtitle),
+        ...t('caption', c.caption),
         '--dct-header-pad': c.spacing.headerPadding,
         '--dct-legend-pad': c.spacing.legendPadding,
         '--dct-caption-pad': c.spacing.captionPadding,
@@ -282,9 +350,10 @@ export function configToCssVars(c) {
         '--dct-divider-style': c.divider.style,
         '--dct-divider-margin': c.divider.margin,
         '--dct-row-gap': c.chrome.rowGap,
-        ...t('title', c.title),
-        ...t('subtitle', c.subtitle),
-        ...t('caption', c.caption),
+        '--dct-heat-min': c.continuous.min,
+        '--dct-heat-max': c.continuous.max,
+        '--dct-heat-text': c.continuous.labelColor,
+        '--dct-axis-color': c.axis.color,
         '--dct-legend-font': c.legend.font,
         '--dct-legend-size': c.legend.size,
         '--dct-legend-weight': String(c.legend.weight),
@@ -312,13 +381,22 @@ export function configToCssVars(c) {
         '--dct-continuous-label-size': c.legend.continuous.label.size,
         '--dct-continuous-label-weight': String(c.legend.continuous.label.weight),
         '--dct-continuous-label-overlap-rotate': c.legend.continuous.label.overlap.rotate,
-        '--dct-axis-color': c.axis.color,
         '--dct-tooltip-bg': c.tooltip.background,
         '--dct-tooltip-color': c.tooltip.color,
         '--dct-tooltip-size': c.tooltip.fontSize,
         '--dct-tooltip-pad': c.tooltip.padding,
         '--dct-tooltip-radius': c.tooltip.radius,
         '--dct-tooltip-border': c.tooltip.border,
+        '--dct-facet-indicator-bg': c.facet.indicator.background,
+        '--dct-facet-indicator-color': c.facet.indicator.color,
+        '--dct-facet-indicator-size': c.facet.indicator.fontSize,
+        '--dct-facet-indicator-pad': c.facet.indicator.padding,
+        '--dct-facet-indicator-radius': c.facet.indicator.radius,
+        '--dct-facet-nav-bg': c.facet.navButton.background,
+        '--dct-facet-nav-color': c.facet.navButton.color,
+        '--dct-facet-nav-btn-size': c.facet.navButton.size,
+        '--dct-facet-nav-font-size': c.facet.navButton.fontSize,
+        '--dct-facet-nav-disabled-opacity': String(c.facet.navButton.disabledOpacity),
         '--dct-timeline-axis': c.timeline.axisColor,
         '--dct-timeline-active': c.timeline.activeColor,
         '--dct-timeline-gap': c.timeline.gap,
@@ -347,20 +425,7 @@ export function configToCssVars(c) {
         '--dct-player-toggle-active-color': c.timeline.player.toggle.activeColor,
         '--dct-player-toggle-radius': c.timeline.player.toggle.radius,
         '--dct-player-toggle-size': c.timeline.player.toggle.fontSize,
-        '--dct-player-toggle-pad': c.timeline.player.toggle.padding,
-        '--dct-heat-min': c.continuous.min,
-        '--dct-heat-max': c.continuous.max,
-        '--dct-heat-text': c.continuous.labelColor,
-        '--dct-facet-indicator-bg': c.facet.indicator.background,
-        '--dct-facet-indicator-color': c.facet.indicator.color,
-        '--dct-facet-indicator-size': c.facet.indicator.fontSize,
-        '--dct-facet-indicator-pad': c.facet.indicator.padding,
-        '--dct-facet-indicator-radius': c.facet.indicator.radius,
-        '--dct-facet-nav-bg': c.facet.navButton.background,
-        '--dct-facet-nav-color': c.facet.navButton.color,
-        '--dct-facet-nav-btn-size': c.facet.navButton.size,
-        '--dct-facet-nav-font-size': c.facet.navButton.fontSize,
-        '--dct-facet-nav-disabled-opacity': String(c.facet.navButton.disabledOpacity)
+        '--dct-player-toggle-pad': c.timeline.player.toggle.padding
     };
 }
 /** Serialize a CSS-vars record into a `style` attribute string. */