@fundar/data-chart-telling 1.2.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +2 -1
  3. package/dist/configuration/config.svelte.js +12 -0
  4. package/dist/layout/facet/scope.d.ts +40 -0
  5. package/dist/layout/facet/scope.js +104 -0
  6. package/dist/layout/figure/Figure.svelte +5 -0
  7. package/dist/layout/legend/DiscreteSymbolIcon.svelte +38 -14
  8. package/dist/layout/legend/LegendState.svelte.d.ts +11 -0
  9. package/dist/layout/legend/LegendState.svelte.js +56 -6
  10. package/dist/layout/margins/PlotMargins.svelte.d.ts +9 -5
  11. package/dist/layout/margins/PlotMargins.svelte.js +65 -6
  12. package/dist/layout/plot/Plot.svelte +22 -2
  13. package/dist/layout/scales/ScalesLayout.svelte +21 -0
  14. package/dist/markers/delta/Delta.d.ts +6 -1
  15. package/dist/markers/delta/Delta.js +15 -0
  16. package/dist/markers/delta/DeltaMarker.svelte +9 -87
  17. package/dist/markers/delta/DeltaPoint.svelte +97 -0
  18. package/dist/markers/delta/DeltaPoint.svelte.d.ts +29 -0
  19. package/dist/markers/rule/RuleMarker.svelte +5 -2
  20. package/dist/phases/facet/FacetPhase.d.ts +2 -1
  21. package/dist/phases/facet/FacetPhase.js +19 -4
  22. package/dist/phases/statistics/StatisticsPhase.js +9 -1
  23. package/dist/plots/utils/segments.d.ts +4 -1
  24. package/dist/plots/utils/segments.js +19 -6
  25. package/dist/types/configuration/styling.d.ts +8 -0
  26. package/dist/types/layout/facet.d.ts +18 -0
  27. package/dist/types/layout/legend.d.ts +16 -0
  28. package/dist/types/layout/plot.d.ts +2 -0
  29. package/dist/types/markers/axis/delta.d.ts +15 -2
  30. package/dist/types/markers/axis/rule.d.ts +9 -2
  31. package/dist/types/phases/facet/phase.d.ts +4 -0
  32. package/dist/types/plots/props.d.ts +6 -3
  33. package/dist/types/plots/segments/config.d.ts +4 -2
  34. package/docs/facets.md +47 -0
  35. package/docs/legend.md +14 -0
  36. package/docs/markers.md +54 -26
  37. package/docs/styles-and-segments.md +1 -0
  38. package/docs/theming.md +1 -1
  39. package/examples/FacetsScoped.svelte +26 -0
  40. package/llms-full.txt +5 -3
  41. package/llms.txt +1 -0
  42. package/package.json +1 -1
package/docs/facets.md CHANGED
@@ -106,6 +106,53 @@ The data phases (grouping, transforms, statistics, shared scales) run once for a
106
106
 
107
107
  ![Panels for each combination of region and sector](images/facets-rows-cols.png)
108
108
 
109
+ ## Markers and segments in some panels
110
+
111
+ Every panel draws the plot's `markers` and `segments`. Add `facet` to one to limit it to the panels it names: the value of its `by` field, or a list of them. Without `facet` it applies to every panel, as before.
112
+
113
+ <!-- example: examples/FacetsScoped.svelte -->
114
+
115
+ ```svelte
116
+ <script lang="ts">
117
+ import { LinePlot } from '@fundar/data-chart-telling';
118
+ import { REGION_VALUES } from './datasets';
119
+
120
+ // Each region's value split into two sectors.
121
+ const SECTORS = [
122
+ { sector: 'Goods', share: 0.8 },
123
+ { sector: 'Services', share: 1.4 }
124
+ ];
125
+ const rows = REGION_VALUES.flatMap((row) =>
126
+ SECTORS.map(({ sector, share }) => ({ ...row, sector, value: row.value * share }))
127
+ );
128
+ </script>
129
+
130
+ <!-- One panel per region. `facet` on a marker or a segment limits it to the panels it names: the rule is drawn in GBA only, and Services is dashed in Cuyo only. -->
131
+ <LinePlot
132
+ width={900}
133
+ height={360}
134
+ data={rows}
135
+ x="date"
136
+ y="value"
137
+ color="sector"
138
+ facet={{ by: 'region', columns: 3 }}
139
+ markers={[{ type: 'rule', axis: 'y', value: 10, facet: 'GBA' }]}
140
+ segments={{ Services: [{ facet: 'Cuyo', styles: { stroke: { strokeDasharray: '4 4' } } }] }}
141
+ />
142
+ ```
143
+
144
+ <!-- /example -->
145
+
146
+ ![Markers and segments in some panels](images/facets-scoped.png)
147
+
148
+ | `facet` | Applies to |
149
+ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
150
+ | _not set_ | Every panel, and a plot with no facet |
151
+ | `'GBA'` or `['GBA', 'Cuyo']` | The panels with that `by` value (numbers and booleans match the text they print as) |
152
+ | `{ row: 'GBA' }`, `{ col: 'Goods' }` | In a `rows`/`cols` grid, the panels with that row or column value; `{ row, col }` takes both, and a side left out matches every value of it |
153
+
154
+ A marker or a segment that names a facet is not drawn by a plot that has none. It works on every plot kind: a `GeoPlot` map takes it the same way, on top of slicing its marker rows by the facet field.
155
+
109
156
  ## Alignment
110
157
 
111
158
  Panels line up: each plot reports the margins it settled on, and once all have, every column and row pins its widest ones, so the plot areas align whatever their tick labels need.
package/docs/legend.md CHANGED
@@ -101,6 +101,20 @@ legend={{
101
101
 
102
102
  Each key is the name of the channel (the plot's own prop: `r` for the size section) and adjusts the section that channel draws: any section field except what the plots compute (items, ranges, domains). An entry with `match` adjusts only the section whose title matches; a list of entries adjusts several.
103
103
 
104
+ ### Turning series off from code
105
+
106
+ `off` turns series off as if the reader had clicked them, without a click: a list of names (each dimmed, to `legend.disabledOpacity`), or a name → opacity or name → action map, where an action is the same `{ mode: 'dim' | 'hide' | 'omit' }` a toggle does. `highlight` is its inverse: it keeps the series it names on and dims all the others. An `off` entry for a series wins over `highlight`.
107
+
108
+ ```ts
109
+ legend={{ off: ['2020'] }} // dim
110
+ legend={{ off: { '2020': 0.1, '2021': { mode: 'omit' } } }} // dim to 0.1, drop from the plot
111
+ legend={{ highlight: 'Argentina' }} // everything else dims
112
+ // A facet plot: dim a series only when no panel shows it.
113
+ legend={{ off: ages.filter((age) => facets.every((f) => !visible[f].includes(age))) }}
114
+ ```
115
+
116
+ They follow the value they are given: a series left out is turned back on, and one the reader turned off themselves is left as it is.
117
+
104
118
  ## Explicit sections
105
119
 
106
120
  A list replaces the automatic legend with exactly those sections:
package/docs/markers.md CHANGED
@@ -58,32 +58,60 @@ Many markers also take channel fields (`color`, `fill`, `opacity`, `r`, `symbol`
58
58
 
59
59
  ## Catalog for axis-based plots
60
60
 
61
- | `type` | Draws |
62
- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
63
- | `dot` | A point per row; `r`, `color`, `symbol`, `styles` (`DotStyle`) |
64
- | `text` | A label per row; `text` (string or function), `styles` (`FontStyle`), `declutter`, `edgeAware`, `fitMargins` |
65
- | `line` | A line through the rows |
66
- | `rule` | A reference line: `axis: 'x' \| 'y'`, `value` (or a function with `data`), `styles`; with `data`, `stroke`, `strokeWidth` and `strokeOpacity` also take a field or function per row |
67
- | `tick` | A short tick per row along one axis |
68
- | `bar` | A bar; `rect`, `cell`: rectangles and heatmap cells |
69
- | `rect` | A rectangle from `x1`/`x2`/`y1`/`y2`; `interval` turns `x`/`y` into ranges |
70
- | `area` | A filled area under a curve, or between `y1` and `y2`; `curve` |
71
- | `difference` | The area between two series, colored by which one is on top |
72
- | `arrow` | An arrow from `x1,y1` to `x2,y2`; `bend`, `headAngle`, `headLength`; with `data`, `stroke`, `strokeWidth` and `strokeOpacity` also take a field or function per row |
73
- | `trail` | A variable-width ribbon along a path, its width set by `r` |
74
- | `delta` | The distance between two series (or a series and a fixed value) at a position, as a line and a label |
75
- | `hull` | The convex hull around a cluster of points |
76
- | `density` | 2D density contour bands |
77
- | `box` | A box plot; sub-marks styled through `bar`, `rule`, `dot`, `tickMedian`, `tickMinMax`; `thickness` sets its width in pixels, `slot` its share of a band |
78
- | `violin` | A violin per category of its rows: the mirrored density of `y` (or `x`), `kernel`, `bandwidth`, `trim`, `peak`, `slot`; add a narrow `box` over the same rows for the box inside |
79
- | `regression`, `bollinger` | A fitted curve, a moving-average band |
80
- | `waffle` | The value as a grid of unit squares; `unit`, `multiple`, `gap` |
81
- | `voronoi`, `voronoiMesh`, `delaunayLink`, `delaunayMesh` | Voronoi cells and Delaunay triangulation |
82
- | `image` | An image per row; `src`, `width`, `height` |
83
- | `raster` | A field sampled over a rectangle, drawn to a canvas |
84
- | `brush` | A drag-to-select rectangle with `onbrushstart`, `onbrush`, `onbrushend` |
85
- | `hover` | The in-plot hover highlight (see below) |
86
- | `component` | Your own Svelte component (see below) |
61
+ | `type` | Draws |
62
+ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
63
+ | `dot` | A point per row; `r`, `color`, `symbol`, `styles` (`DotStyle`) |
64
+ | `text` | A label per row; `text` (string or function), `styles` (`FontStyle`), `declutter`, `edgeAware`, `fitMargins` |
65
+ | `line` | A line through the rows |
66
+ | `rule` | A reference line: `axis: 'x' \| 'y'`, `value` (a list draws a line at each, or a function with `data`), `styles`; with `data`, `stroke`, `strokeWidth` and `strokeOpacity` also take a field or function per row |
67
+ | `tick` | A short tick per row along one axis |
68
+ | `bar` | A bar; `rect`, `cell`: rectangles and heatmap cells |
69
+ | `rect` | A rectangle from `x1`/`x2`/`y1`/`y2`; `interval` turns `x`/`y` into ranges |
70
+ | `area` | A filled area under a curve, or between `y1` and `y2`; `curve` |
71
+ | `difference` | The area between two series, colored by which one is on top |
72
+ | `arrow` | An arrow from `x1,y1` to `x2,y2`; `bend`, `headAngle`, `headLength`; with `data`, `stroke`, `strokeWidth` and `strokeOpacity` also take a field or function per row |
73
+ | `trail` | A variable-width ribbon along a path, its width set by `r` |
74
+ | `delta` | The distance between two series (or a series and a fixed value) at a position - or at each of a list of them, `at: [1980, 2000]` - as a line and a label |
75
+ | `hull` | The convex hull around a cluster of points |
76
+ | `density` | 2D density contour bands |
77
+ | `box` | A box plot; sub-marks styled through `bar`, `rule`, `dot`, `tickMedian`, `tickMinMax`; `thickness` sets its width in pixels, `slot` its share of a band |
78
+ | `violin` | A violin per category of its rows: the mirrored density of `y` (or `x`), `kernel`, `bandwidth`, `trim`, `peak`, `slot`; add a narrow `box` over the same rows for the box inside |
79
+ | `regression`, `bollinger` | A fitted curve, a moving-average band |
80
+ | `waffle` | The value as a grid of unit squares; `unit`, `multiple`, `gap` |
81
+ | `voronoi`, `voronoiMesh`, `delaunayLink`, `delaunayMesh` | Voronoi cells and Delaunay triangulation |
82
+ | `image` | An image per row; `src`, `width`, `height` |
83
+ | `raster` | A field sampled over a rectangle, drawn to a canvas |
84
+ | `brush` | A drag-to-select rectangle with `onbrushstart`, `onbrush`, `onbrushend` |
85
+ | `hover` | The in-plot hover highlight (see below) |
86
+ | `component` | Your own Svelte component (see below) |
87
+
88
+ ## Markers in some facets
89
+
90
+ On a plot with a [`facet`](facets.md#markers-and-segments-in-some-panels), every marker is drawn in every panel. A marker takes `facet`, a panel's value or a list of them, to be drawn only in the panels it names.
91
+
92
+ ## Several positions at once
93
+
94
+ A `rule` takes a list as its `value`, and a `delta` a list as its `at`. One marker then draws one line, or one delta, at each position, all with the same style and the same ends - instead of one marker for each.
95
+
96
+ ```ts
97
+ markers={[
98
+ // A rule at each of the three years.
99
+ { type: 'rule', axis: 'x', value: [1991, 2001, 2010], styles: { strokeDasharray: '4 4' } },
100
+ // The gap between the two series at each of the three.
101
+ { type: 'delta', axis: 'x', at: [1991, 2001, 2010], from: { type: 'series', series: 'female' }, to: { type: 'series', series: 'male' } }
102
+ ]}
103
+ ```
104
+
105
+ A delta's `line`, `text` and `dot` can be functions of the position, to style each one on its own - a label to the left of the last one, say, so it stays inside the plot:
106
+
107
+ ```ts
108
+ {
109
+ type: 'delta', axis: 'x', at: [1991, 2001, 2022], from: { type: 'series', series: 'female' }, to: { type: 'series', series: 'male' },
110
+ text: (at) => (at === 2022 ? { dx: -20, textAnchor: 'end' } : { dx: 20 })
111
+ }
112
+ ```
113
+
114
+ Every other marker draws from `data` rows, one mark per row, so it already takes many positions.
87
115
 
88
116
  ## Hover highlight
89
117
 
@@ -119,6 +119,7 @@ type Range = { from?: AxisValue; to?: AxisValue }; // inclusive on both ends
119
119
  - A segment without `areas` is a **catch-all**: it matches every point, is evaluated last, and is overridden by any area-specific segment. A catch-all placed first is a baseline that highlighted ranges override.
120
120
  - `'default'` applies to every series; a named key applies to that series only, and wins over `'default'` where both match.
121
121
  - `legend` names the segment on the automatic [legend](legend.md).
122
+ - `facet` limits the segment to the [facet panels](facets.md#markers-and-segments-in-some-panels) it names - a `by` value or a list of them. Without it the segment applies to every panel.
122
123
 
123
124
  The style shape depends on the plot:
124
125
 
package/docs/theming.md CHANGED
@@ -40,7 +40,7 @@ resetConfiguration(); // back to the shipped defaults
40
40
  | `spacing`, `chrome` | Padding around header, legend and caption; the chrome `order` and `rowGap` |
41
41
  | `title`, `subtitle`, `caption` | Text blocks: `font`, `size`, `weight`, `color`, `leading`, `spacing` |
42
42
  | `divider` | The line a `'divider'` in the chrome `order` draws |
43
- | `legend` | Text, gaps, swatches, `disabledOpacity`, paginated nav buttons, the continuous bar, its handles, ticks and labels, and the `seriesTitle` and `sizeScale` options |
43
+ | `legend` | Text, gaps, swatches, the series `icon` (`rounded`, and the shape each mark draws as in `marks`), `disabledOpacity`, paginated nav buttons, the continuous bar, its handles, ticks and labels, and the `seriesTitle` and `sizeScale` options |
44
44
  | `axis` | Axis color, font and tick sizes, `grid`, and the number locale (below) |
45
45
  | `tooltip` | Tooltip background, color, font size, padding, radius, border |
46
46
  | `margins` | Default margin per side (`'auto'` or a number) |
@@ -0,0 +1,26 @@
1
+ <script lang="ts">
2
+ import { LinePlot } from '@fundar/data-chart-telling';
3
+ import { REGION_VALUES } from './datasets';
4
+
5
+ // Each region's value split into two sectors.
6
+ const SECTORS = [
7
+ { sector: 'Goods', share: 0.8 },
8
+ { sector: 'Services', share: 1.4 }
9
+ ];
10
+ const rows = REGION_VALUES.flatMap((row) =>
11
+ SECTORS.map(({ sector, share }) => ({ ...row, sector, value: row.value * share }))
12
+ );
13
+ </script>
14
+
15
+ <!-- One panel per region. `facet` on a marker or a segment limits it to the panels it names: the rule is drawn in GBA only, and Services is dashed in Cuyo only. -->
16
+ <LinePlot
17
+ width={900}
18
+ height={360}
19
+ data={rows}
20
+ x="date"
21
+ y="value"
22
+ color="sector"
23
+ facet={{ by: 'region', columns: 3 }}
24
+ markers={[{ type: 'rule', axis: 'y', value: 10, facet: 'GBA' }]}
25
+ segments={{ Services: [{ facet: 'Cuyo', styles: { stroke: { strokeDasharray: '4 4' } } }] }}
26
+ />
package/llms-full.txt CHANGED
@@ -68,6 +68,7 @@ Per kind: `BarPlot` x = category, y = value (swap for horizontal bars); `Pyramid
68
68
  7. `r` takes raw values and its sqrt scale makes area follow the value; tune with `scales.r.range`. A literal number is a fixed pixel radius.
69
69
  8. Narrow plots with long category or series names: shorten the text in the data, format with `tickFormat` / `values.format`, or give `margins` more room.
70
70
  9. In Svelte 5 components, `state` is taken by the `$state` rune: name local variables otherwise.
71
+ 10. In a `facet`, every panel draws the plot's `markers` and `segments`. Give one a `facet` (a `by` value, a list of them, or `{ row, col }` in a `rows`/`cols` grid) to draw it only in the panels it names: `markers={[{ type: 'rule', axis: 'y', value: 10, facet: 'GBA' }]}`, `segments={{ Services: [{ facet: 'Cuyo', styles: { stroke: { strokeDasharray: '4 4' } } }] }}`. A plot with no facet leaves out whatever names one.
71
72
  10. Stacking is `transforms={[{ type: 'stackY' }]}`, also for horizontal bars (the value channel is the one stacked).
72
73
 
73
74
  ## Reading and driving plot state (custom UI)
@@ -88,13 +89,13 @@ Add with `markers={[{ type: '...' }]}`. For x/y plots:
88
89
  `area arrow bar bollinger box brush cell component delaunayLink delaunayMesh delta density difference dot hover hull image line raster rect regression rule text tick trail violin voronoi voronoiMesh waffle`.
89
90
  GeoPlot: `graticule sphere dot text vector link contour inset geo-hover geo-component`.
90
91
 
91
- - `delta` annotates the difference between two series at a position: `{ type: 'delta', axis: 'x', at: 2020, from: { type: 'series', series: 'A' }, to: { type: 'series', series: 'B' }, formatDiff: (d) => d.toFixed(1) }`.
92
- - `rule` (`axis`, `value`), `text` (`text`), `dot` annotate; `component` mounts your own Svelte component inside the plot (it can call `usePlot()`).
92
+ - `delta` annotates the difference between two series at a position: `{ type: 'delta', axis: 'x', at: 2020, from: { type: 'series', series: 'A' }, to: { type: 'series', series: 'B' }, formatDiff: (d) => d.toFixed(1) }`; `at` can be a list of positions, one delta at each (`at: [1991, 2001]`), and `line`, `text` and `dot` can be functions of the position (`text: (at) => at === 2022 ? { dx: -20, textAnchor: 'end' } : { dx: 20 }`).
93
+ - `rule` (`axis`, `value`; a list draws a line at each), `text` (`text`), `dot` annotate; `component` mounts your own Svelte component inside the plot (it can call `usePlot()`).
93
94
  - Each plot kind types its own marker union (`AxisBasedMarkersConfig`, `GeoMarkersConfig`); `satisfies` on a markers array gives completion.
94
95
 
95
96
  ## Theming and locale
96
97
 
97
- - `setConfiguration(partial)` deep-merges global defaults (colors, fonts, spacing, legend, tooltip, timeline); `resetConfiguration()` restores them. Inside an `$effect`, wrap the call in `untrack`.
98
+ - `setConfiguration(partial)` deep-merges global defaults (colors, fonts, spacing, legend, tooltip, timeline); `resetConfiguration()` restores them. Legend series icons: `legend.icon.rounded` (default `false`) and `legend.icon.marks` (shape per mark: `line`, `dot`, `area`, `bar`, `cell`, `rect`, `geo`; a symbol or `'line'`). Inside an `$effect`, wrap the call in `untrack`.
98
99
  - `THEMES` has `Default Editorial Dark Compact`: `setConfiguration(THEMES.Editorial)`.
99
100
  - Number and date text follows `axis.locale` (default `'es-AR'`) in the configuration; per axis, `tickFormat: (d) => new Intl.NumberFormat('en-US').format(d)` or an `Intl.*FormatOptions` object.
100
101
 
@@ -150,4 +151,5 @@ GeoPlot: `graticule sphere dot text vector link contour inset geo-hover geo-comp
150
151
  - `ChromeOrder.svelte` - ordering chrome blocks with dividers.
151
152
  - `FacetsCarousel.svelte` - facets as a carousel.
152
153
  - `FacetsRowsCols.svelte` - facets by rows and columns.
154
+ - `FacetsScoped.svelte` - markers and segments in some facet panels.
153
155
  - `Composer.svelte` - several plots in one figure.
package/llms.txt CHANGED
@@ -92,6 +92,7 @@ Start with the full guide: it lists the mental model, the props every plot share
92
92
  - [Ordering chrome blocks with dividers](./examples/ChromeOrder.svelte)
93
93
  - [Facets as a carousel](./examples/FacetsCarousel.svelte)
94
94
  - [Facets by rows and columns](./examples/FacetsRowsCols.svelte)
95
+ - [Markers and segments in some facet panels](./examples/FacetsScoped.svelte)
95
96
  - [Several plots in one figure](./examples/Composer.svelte)
96
97
  - [Example datasets, one file each](./examples/datasets)
97
98
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fundar/data-chart-telling",
3
- "version": "1.2.0",
3
+ "version": "1.4.0",
4
4
  "description": "Declarative charts, maps and small multiples for Svelte, built on svelteplot.",
5
5
  "license": "MIT",
6
6
  "author": "Ezequiel Puerta",