@blueprint-chart/docs 2.5.1 → 2.6.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.
- package/dist/manifest.json +7 -0
- package/package.json +3 -3
- package/src/charts/index.md +5 -1
- package/src/charts/scatter.md +208 -0
- package/src/reference/dsl/index.md +1 -1
package/dist/manifest.json
CHANGED
|
@@ -238,6 +238,13 @@
|
|
|
238
238
|
"blurb": "> Circular part-to-whole chart for very small N.",
|
|
239
239
|
"mdPath": "charts/pie.md"
|
|
240
240
|
},
|
|
241
|
+
{
|
|
242
|
+
"slug": "scatter",
|
|
243
|
+
"group": "charts",
|
|
244
|
+
"title": "Scatter chart",
|
|
245
|
+
"blurb": "> Points placed by two numeric values, to show how one variable relates to another.",
|
|
246
|
+
"mdPath": "charts/scatter.md"
|
|
247
|
+
},
|
|
241
248
|
{
|
|
242
249
|
"slug": "annotations",
|
|
243
250
|
"group": "reference/dsl",
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@blueprint-chart/docs",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.6.0",
|
|
4
4
|
"description": "Public documentation for Blueprint Chart — handbook, guide, BPC DSL spec, and lib API reference.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -33,8 +33,8 @@
|
|
|
33
33
|
"provenance": true
|
|
34
34
|
},
|
|
35
35
|
"devDependencies": {
|
|
36
|
-
"@blueprint-chart/lib": "2.
|
|
37
|
-
"@blueprint-chart/ui": "2.
|
|
36
|
+
"@blueprint-chart/lib": "2.6.0",
|
|
37
|
+
"@blueprint-chart/ui": "2.6.0",
|
|
38
38
|
"@fontsource-variable/geist": "^5.3.0",
|
|
39
39
|
"@fontsource-variable/geist-mono": "^5.3.0",
|
|
40
40
|
"@fontsource/dm-serif-display": "^5.3.0",
|
package/src/charts/index.md
CHANGED
|
@@ -4,7 +4,7 @@ title: Chart types
|
|
|
4
4
|
|
|
5
5
|
# Chart types
|
|
6
6
|
|
|
7
|
-
Blueprint Chart ships
|
|
7
|
+
Blueprint Chart ships 14 chart types organized into five families: bar, line, area, part-to-whole, and relationship.
|
|
8
8
|
|
|
9
9
|
## Bar family
|
|
10
10
|
|
|
@@ -31,6 +31,10 @@ Blueprint Chart ships 13 chart types organized into four families: bar, line, ar
|
|
|
31
31
|
- [`pie`](./pie) — circular part-to-whole, very small N
|
|
32
32
|
- [`donut`](./donut) — circular part-to-whole with a central label slot
|
|
33
33
|
|
|
34
|
+
## Relationship
|
|
35
|
+
|
|
36
|
+
- [`scatter`](./scatter): points placed by two numeric values; optional bubble size and color groups
|
|
37
|
+
|
|
34
38
|
::: tip Choosing the right chart
|
|
35
39
|
Not sure which type fits your data? Start with the decision framework in the [choosing the right chart](/handbook/choosing) handbook entry.
|
|
36
40
|
:::
|
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Scatter chart
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Scatter chart
|
|
6
|
+
|
|
7
|
+
> Points placed by two numeric values, to show how one variable relates to another.
|
|
8
|
+
|
|
9
|
+
`scatter` draws one point per row. The x and y positions come from two numeric columns. A third numeric column can size each point as a bubble, and a text column can color points by group. See [Properties](#properties) for every key it accepts.
|
|
10
|
+
|
|
11
|
+
## When to use
|
|
12
|
+
|
|
13
|
+
- Showing whether two measures move together (wealth and life expectancy, price and sales)
|
|
14
|
+
- Spotting clusters and outliers that a table hides
|
|
15
|
+
- Comparing groups on the same two measures, with one color per group
|
|
16
|
+
|
|
17
|
+
## When NOT to use
|
|
18
|
+
|
|
19
|
+
- One of the variables is a category or a date (use [`bar-vertical`](./bar-vertical) or [`line`](./line))
|
|
20
|
+
- The story is a ranking or a total (use a bar chart)
|
|
21
|
+
- Very few points: a short table or a bar chart reads faster
|
|
22
|
+
|
|
23
|
+
## Data shape
|
|
24
|
+
|
|
25
|
+
Each row is one point. The row label is the point's name: it names the tooltip, the label and the target of `highlight`, `colorize` and annotations. Number cells feed the axes and the bubble size. Quoted text cells form a group column.
|
|
26
|
+
|
|
27
|
+
```bpc
|
|
28
|
+
chart scatter {
|
|
29
|
+
data {
|
|
30
|
+
series = "GDP per capita","Life expectancy","Population","Region"
|
|
31
|
+
"France" = 53449, 82.8, 67.4, "Europe & Central Asia"
|
|
32
|
+
"Kenya" = 5172, 62.9, 51.2, "Sub-Saharan Africa"
|
|
33
|
+
"Japan" = 46055, 84.4, 126.6, "East Asia & Pacific"
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Column mapping
|
|
39
|
+
|
|
40
|
+
Columns map to roles by order. Override a role by naming a column.
|
|
41
|
+
|
|
42
|
+
| Property | Role | Inferred from |
|
|
43
|
+
| --- | --- | --- |
|
|
44
|
+
| `x` | Horizontal position | 1st numeric column |
|
|
45
|
+
| `y` | Vertical position | 2nd numeric column |
|
|
46
|
+
| `size` | Bubble area | 3rd numeric column |
|
|
47
|
+
| `group` | Point color and legend | 1st text column |
|
|
48
|
+
|
|
49
|
+
- `x = "Life expectancy"` puts that column on the horizontal axis. The remaining numeric columns fill the other roles in order.
|
|
50
|
+
- `size = "none"` draws uniform dots even when a third numeric column exists. `group = "none"` drops the group colors.
|
|
51
|
+
- Size encodes area, not radius: a value twice as large draws a bubble with twice the area. A size key shows reference circles.
|
|
52
|
+
- A name that matches no column is an error, with a suggestion when one is close.
|
|
53
|
+
- Scatter needs at least two numeric columns. Rows with a missing x or y, or a size of 0 or below, are not drawn and are reported.
|
|
54
|
+
|
|
55
|
+
## Trend line
|
|
56
|
+
|
|
57
|
+
`trend` draws a least-squares line. It is off by default.
|
|
58
|
+
|
|
59
|
+
- `trend = "overall"` fits one line through every point.
|
|
60
|
+
- `trend = "per-group"` fits one line per group, in the group color.
|
|
61
|
+
|
|
62
|
+
The line is dashed, sits beneath the points and appears as `Trend` in the key. It spans only the points it fits and never extends past them. A set with fewer than 3 points gets no line, and a warning says so.
|
|
63
|
+
|
|
64
|
+
## Log scales
|
|
65
|
+
|
|
66
|
+
`horizontalScaleType` sets the x axis and `verticalScaleType` sets the y axis. Both default to `linear`.
|
|
67
|
+
|
|
68
|
+
- `"log"` is a true base-10 scale with ticks at powers of ten. Values of 0 or below cannot sit on it: those rows are dropped and reported. A range bound of 0 or below is ignored, with a warning.
|
|
69
|
+
- `"symlog"` compresses large values like a log scale but keeps 0 and negative values.
|
|
70
|
+
|
|
71
|
+
On other chart types, `"log"` behaves like `"symlog"`. A trend line fits in the scale of each axis, so it stays straight on a log or symlog axis.
|
|
72
|
+
|
|
73
|
+
## Labels
|
|
74
|
+
|
|
75
|
+
Point labels are off by default. A point gets a label when it is highlighted or targeted by an annotation. `showLabels = true` labels every point. When a label has no room, it is dropped rather than drawn over another one.
|
|
76
|
+
|
|
77
|
+
## Highlight and colorize
|
|
78
|
+
|
|
79
|
+
`highlight` and `colorize` take a point name or a group name.
|
|
80
|
+
|
|
81
|
+
- `highlight "Nigeria"` emphasizes one point and dims the rest.
|
|
82
|
+
- `highlight "Sub-Saharan Africa"` emphasizes the whole group.
|
|
83
|
+
- `colorize "Sub-Saharan Africa" { color = "#e15759" }` recolors a group. Naming a point recolors that point only.
|
|
84
|
+
|
|
85
|
+
When a name matches both a point and a group, the point wins.
|
|
86
|
+
|
|
87
|
+
## Scenes
|
|
88
|
+
|
|
89
|
+
Points are matched by name across [scenes](/reference/dsl/scenes-and-transforms). A point present in both scenes glides to its new position, size and color. New points fade in, removed points fade out, and the axes rescale. Keep row names identical between scenes so points move instead of being replaced.
|
|
90
|
+
|
|
91
|
+
## Accessibility
|
|
92
|
+
|
|
93
|
+
The chart is exposed to screen readers as a single image. Its name is the title. Its description is your `description` followed by a point count. Write a `description` that states the relationship in words, since a screen reader does not walk the points. The group legend prints each group name next to its swatch, so color is never the only cue.
|
|
94
|
+
|
|
95
|
+
## Example
|
|
96
|
+
|
|
97
|
+
Trimmed from `packages/lib/src/samples/life-expectancy-wealth.bpc`. Switch scenes to watch each country move.
|
|
98
|
+
|
|
99
|
+
```bpc
|
|
100
|
+
chart scatter {
|
|
101
|
+
title = "Richer countries live longer, but Nigeria lags far behind its wealth"
|
|
102
|
+
description = "Life expectancy in years against GDP per capita (PPP, constant international dollars, log scale), bubble size is population in millions"
|
|
103
|
+
source = "World Bank, World Development Indicators"
|
|
104
|
+
sourceUrl = "https://databank.worldbank.org/source/world-development-indicators"
|
|
105
|
+
horizontalScaleType = "log"
|
|
106
|
+
trend = "overall"
|
|
107
|
+
|
|
108
|
+
data {
|
|
109
|
+
series = "GDP per capita","Life expectancy","Population","Region"
|
|
110
|
+
"Bangladesh" = 6838, 72.6, 164.9, "South Asia"
|
|
111
|
+
"Brazil" = 18019, 75.8, 207.5, "Americas"
|
|
112
|
+
"Canada" = 57584, 82.2, 37.6, "Americas"
|
|
113
|
+
"China" = 18821, 77.9, 1407.7, "East Asia & Pacific"
|
|
114
|
+
"Egypt" = 15027, 71.2, 107.6, "Middle East, North Africa, Afghanistan & Pakistan"
|
|
115
|
+
"Ethiopia" = 2438, 65.7, 115.7, "Sub-Saharan Africa"
|
|
116
|
+
"France" = 53449, 82.8, 67.4, "Europe & Central Asia"
|
|
117
|
+
"India" = 7702, 70.7, 1389.0, "South Asia"
|
|
118
|
+
"Japan" = 46055, 84.4, 126.6, "East Asia & Pacific"
|
|
119
|
+
"Kenya" = 5172, 62.9, 51.2, "Sub-Saharan Africa"
|
|
120
|
+
"Mexico" = 21704, 74.5, 125.8, "Americas"
|
|
121
|
+
"Nigeria" = 8362, 53.0, 209.5, "Sub-Saharan Africa"
|
|
122
|
+
"Norway" = 90773, 83.0, 5.3, "Europe & Central Asia"
|
|
123
|
+
"United States" = 69121, 78.8, 330.2, "Americas"
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
highlight "Nigeria"
|
|
127
|
+
|
|
128
|
+
scene "1990" {
|
|
129
|
+
title = "In 1990 the same countries were poorer and lived shorter lives"
|
|
130
|
+
data {
|
|
131
|
+
series = "GDP per capita","Life expectancy","Population","Region"
|
|
132
|
+
"Bangladesh" = 2070, 55.8, 111.6, "South Asia"
|
|
133
|
+
"Brazil" = 12633, 65.9, 149.1, "Americas"
|
|
134
|
+
"Canada" = 40475, 77.4, 27.7, "Americas"
|
|
135
|
+
"China" = 1667, 68.2, 1135.2, "East Asia & Pacific"
|
|
136
|
+
"Egypt" = 8007, 62.5, 58.4, "Middle East, North Africa, Afghanistan & Pakistan"
|
|
137
|
+
"Ethiopia" = 874, 45.1, 47.6, "Sub-Saharan Africa"
|
|
138
|
+
"France" = 38656, 76.6, 58.3, "Europe & Central Asia"
|
|
139
|
+
"India" = 2140, 58.6, 865.0, "South Asia"
|
|
140
|
+
"Japan" = 36138, 78.8, 123.5, "East Asia & Pacific"
|
|
141
|
+
"Kenya" = 4177, 58.3, 22.9, "Sub-Saharan Africa"
|
|
142
|
+
"Mexico" = 17170, 69.0, 82.8, "Americas"
|
|
143
|
+
"Nigeria" = 5424, 45.7, 97.1, "Sub-Saharan Africa"
|
|
144
|
+
"Norway" = 56608, 76.5, 4.2, "Europe & Central Asia"
|
|
145
|
+
"United States" = 44384, 75.2, 249.6, "Americas"
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
<!-- options:start -->
|
|
152
|
+
|
|
153
|
+
## Properties
|
|
154
|
+
|
|
155
|
+
Every property `scatter` accepts, beside the [frame and layout keys](/reference/dsl/properties) every chart shares. Anything absent from this table is rejected by `validateChart` and ignored by the renderer.
|
|
156
|
+
|
|
157
|
+
| Property | Type | Default |
|
|
158
|
+
| --- | --- | --- |
|
|
159
|
+
| `colors` | colors | (unset) |
|
|
160
|
+
| `colorPalette` | select, see [Palettes](/guide/palettes) | `Blueprint` |
|
|
161
|
+
| `autoContrast` | boolean | `false` |
|
|
162
|
+
| `allowDarkMode` | boolean | `true` |
|
|
163
|
+
| `x` | text | `""` |
|
|
164
|
+
| `y` | text | `""` |
|
|
165
|
+
| `size` | text | `""` |
|
|
166
|
+
| `group` | text | `""` |
|
|
167
|
+
| `trend` | select: `""`, `overall`, `per-group` | `""` |
|
|
168
|
+
| `showLabels` | boolean | `false` |
|
|
169
|
+
| `legend` | boolean | `true` |
|
|
170
|
+
| `legendPosition` | select: `top`, `bottom`, `left`, `right` | `top` |
|
|
171
|
+
| `legendAnchor` | select: `start`, `middle`, `end` | `start` |
|
|
172
|
+
| `tooltips` | boolean | `true` |
|
|
173
|
+
| `showVerticalAxis` | boolean | `false` |
|
|
174
|
+
| `verticalAxisDirection` | select: `left`, `right` | `left` |
|
|
175
|
+
| `showVerticalTicks` | boolean | `false` |
|
|
176
|
+
| `verticalLabelPosition` | select: `auto`, `inside`, `outside`, `off` | `auto` |
|
|
177
|
+
| `verticalGridStyle` | select: `solid`, `dashed`, `dotted`, `none` | `dashed` |
|
|
178
|
+
| `verticalNumberFormat` | numberFormat | (unset) |
|
|
179
|
+
| `verticalScaleType` | select: `linear`, `log`, `symlog` | `linear` |
|
|
180
|
+
| `verticalRangeMin` | text | (unset) |
|
|
181
|
+
| `verticalRangeMax` | text | (unset) |
|
|
182
|
+
| `showHorizontalAxis` | boolean | `true` |
|
|
183
|
+
| `showHorizontalTicks` | boolean | `false` |
|
|
184
|
+
| `horizontalLabelPosition` | select: `auto`, `inside`, `outside`, `off` | `auto` |
|
|
185
|
+
| `horizontalLabelRotation` | select: `auto`, `horizontal`, `vertical` | `horizontal` |
|
|
186
|
+
| `horizontalGridStyle` | select: `solid`, `dashed`, `dotted`, `none` | `dashed` |
|
|
187
|
+
| `horizontalNumberFormat` | numberFormat | (unset) |
|
|
188
|
+
| `horizontalScaleType` | select: `linear`, `log`, `symlog` | `linear` |
|
|
189
|
+
| `horizontalRangeMin` | text | (unset) |
|
|
190
|
+
| `horizontalRangeMax` | text | (unset) |
|
|
191
|
+
|
|
192
|
+
<!-- options:end -->
|
|
193
|
+
|
|
194
|
+
## Common pitfalls
|
|
195
|
+
|
|
196
|
+
- Reading a trend line as proof of cause
|
|
197
|
+
- Mapping a column with zeros or negatives to `size`: those rows are not drawn
|
|
198
|
+
- Too many groups: past five or six colors, the legend stops helping
|
|
199
|
+
|
|
200
|
+
## Related types
|
|
201
|
+
|
|
202
|
+
- [`line`](./line): when x is time and the order of points matters
|
|
203
|
+
- [`bar-grouped`](./bar-grouped): when one dimension is a category
|
|
204
|
+
|
|
205
|
+
## See also
|
|
206
|
+
|
|
207
|
+
- [Choosing the right chart](/handbook/choosing)
|
|
208
|
+
- [Annotations](/reference/dsl/annotations)
|
|
@@ -63,7 +63,7 @@ chart <chartType> {
|
|
|
63
63
|
}
|
|
64
64
|
```
|
|
65
65
|
|
|
66
|
-
Where `<chartType>` is one of the registered chart-type identifiers (`line`, `bar-vertical`, `bar-horizontal`, `bar-grouped`, `bar-stacked`, `bar-multi`, `bar-split`, `column-stacked`, `area`, `area-stacked`, `line-multi`, `pie`, `donut`). The authoritative list is exported as `ChartType` from [`@blueprint-chart/lib`](/reference/api/).
|
|
66
|
+
Where `<chartType>` is one of the registered chart-type identifiers (`line`, `bar-vertical`, `bar-horizontal`, `bar-grouped`, `bar-stacked`, `bar-multi`, `bar-split`, `column-stacked`, `area`, `area-stacked`, `line-multi`, `pie`, `donut`, `scatter`). The authoritative list is exported as `ChartType` from [`@blueprint-chart/lib`](/reference/api/).
|
|
67
67
|
|
|
68
68
|
## Lexical grammar
|
|
69
69
|
|