@pioneer-code/pioneer-charts 22.2.21 → 22.2.23

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.
@@ -103,9 +103,22 @@ class PcacAxisConfig {
103
103
  * margins grow or shrink by the same amount so the plot area makes room for them - a longer
104
104
  * tick means a slightly smaller plot, never labels pushed off the edge. Only the per-tick marks
105
105
  * change; the axis line's two end-caps keep their default length. Colored by `tickColor`, the
106
- * theme's `$gray-900` (like the axis line) by default.
106
+ * theme's `$gray-900` (like the axis line) by default. Ignored while `autoTickSize` is on.
107
107
  */
108
108
  tickSize;
109
+ /**
110
+ * Size the tick marks from the chart's points instead of `tickSize`: half the largest mark
111
+ * toward this axis, so a point sitting on the axis ends where its tick does and never covers a
112
+ * tick label (D3's 3px tick padding is the gap left between them). This **overrides**
113
+ * `tickSize` - with it on, any `tickSize` given is ignored - and turns the marks on the same
114
+ * way a `tickSize` does. The largest mark is measured as drawn: a hovered dot, an image's box
115
+ * (its height for the x axis, its width for the y axis), and a gauge ring around either,
116
+ * after any shrinking to fit (dot plot). Honored by the charts that draw points - line, area,
117
+ * plot and dot plot; ignored elsewhere. On the dot plot the marks never reach the axis (its
118
+ * bottom row sits a `gap` above it), so there it only spaces the labels to the marks' size.
119
+ * Default false.
120
+ */
121
+ autoTickSize = false;
109
122
  /**
110
123
  * Tick mark color (`--pcac-axis-tick-color`), shown once `tickSize` has turned the marks on.
111
124
  * Theme default `$gray-900`.
@@ -202,6 +215,7 @@ function resolveAxisConfig(axis, showGridDefault = false) {
202
215
  showGrid: axis?.showGrid ?? showGridDefault,
203
216
  ticks: axis?.ticks ?? defaults.ticks,
204
217
  showLine: axis?.showLine ?? defaults.showLine,
218
+ autoTickSize: axis?.autoTickSize ?? defaults.autoTickSize,
205
219
  format: axis?.format ?? defaults.format,
206
220
  domainMin: axis?.domainMin ?? defaults.domainMin,
207
221
  domainMax: axis?.domainMax ?? defaults.domainMax,
@@ -1268,7 +1282,8 @@ class PcacChart {
1268
1282
  * In order:
1269
1283
  *
1270
1284
  * 1. `resetMargin()`.
1271
- * 2. Tick marks: room for a non-default `tickSize` is reserved on each axis that will actually
1285
+ * 2. Tick marks: an axis with `autoTickSize` takes its `tickSize` from `autoTickSize` (see below).
1286
+ * Then room for a non-default `tickSize` is reserved on each axis that will actually
1272
1287
  * be drawn (`reserveTickSizeMargins`).
1273
1288
  * 3. Labels: `AXIS_LABEL_SPACE` is added to `bottom` / `left` for an axis with a `label`, and
1274
1289
  * `AXIS_SUB_LABEL_SPACE` for one with any `subLabels` (see `axisLabelSpace`), again only if
@@ -1283,10 +1298,20 @@ class PcacChart {
1283
1298
  * (`PcacAxisConfig.showGrid`): `'y'` for horizontal lines, `'x'` for vertical.
1284
1299
  * @param hiddenAxisMargin what a hidden axis's sides shrink to, rather than 0. The
1285
1300
  * line/area/plot charts keep 8px so a dot on the edge of the plot isn't clipped by the SVG.
1301
+ * @param autoTickSize for the charts that draw points: half their largest mark toward each axis
1302
+ * (`x`: its vertical half, `y`: its horizontal half), which an axis with `autoTickSize` takes,
1303
+ * rounded up, as its `tickSize` - in place of any `tickSize` the consumer gave. Left out, as by
1304
+ * the charts without points, `autoTickSize` does nothing.
1286
1305
  */
1287
- initializeAxisState(config, defaultGrid, hiddenAxisMargin = 0) {
1306
+ initializeAxisState(config, defaultGrid, hiddenAxisMargin = 0, autoTickSize) {
1288
1307
  this.xAxis = resolveAxisConfig(config.xAxis, defaultGrid === 'x');
1289
1308
  this.yAxis = resolveAxisConfig(config.yAxis, defaultGrid === 'y');
1309
+ if (autoTickSize && this.xAxis.autoTickSize) {
1310
+ this.xAxis.tickSize = Math.ceil(autoTickSize.x);
1311
+ }
1312
+ if (autoTickSize && this.yAxis.autoTickSize) {
1313
+ this.yAxis.tickSize = Math.ceil(autoTickSize.y);
1314
+ }
1290
1315
  this.resetMargin();
1291
1316
  this.reserveTickSizeMargins(this.xAxis.hide ? undefined : this.xAxis.tickSize, this.yAxis.hide ? undefined : this.yAxis.tickSize);
1292
1317
  if (!this.xAxis.hide) {
@@ -3018,11 +3043,9 @@ class DotPlotChartBuilder extends PcacChart {
3018
3043
  return;
3019
3044
  }
3020
3045
  this.hideTooltip();
3021
- // A column's height is a count of marks, not a value, so there's no y axis to draw. Shallow
3022
- // copies: initializeAxisState() rewrites `height`, which mustn't reach the consumer's object.
3046
+ // A column's height is a count of marks, not a value, so there's no y axis to draw.
3023
3047
  const rawXAxis = config.xAxis;
3024
3048
  config = { ...config, yAxis: { ...config.yAxis, hide: true } };
3025
- this.initializeAxisState(config, 'x', 0);
3026
3049
  const defaults = new PcacDotPlotChartConfig();
3027
3050
  const dotRadius = config.dotRadius ?? defaults.dotRadius;
3028
3051
  const gap = config.gap ?? defaults.gap;
@@ -3030,26 +3053,53 @@ class DotPlotChartBuilder extends PcacChart {
3030
3053
  const origin = rawXAxis?.domainMin !== undefined ? Number(rawXAxis.domainMin) : 0;
3031
3054
  this.placements = stackDots(config.data, config.binWidth, origin);
3032
3055
  const hasImages = this.placements.some((p) => !!p.data.image);
3056
+ const hasDots = this.placements.some((p) => !p.data.image);
3033
3057
  const fullSize = hasImages
3034
3058
  ? Math.max(this.pointImage.maxWidth, this.pointImage.maxHeight)
3035
3059
  : 2 * (dotRadius + DOT_HOVER_GROWTH);
3036
- // A mark at the domain's edge is centered on it, so half of it hangs past the plot area.
3037
- const half = Math.ceil(fullSize / 2);
3038
- this.reserveEdgeSpace({ left: half, right: half });
3039
- if (!this.initializeChartState(chartElm, config)) {
3040
- return;
3060
+ const tallest = tallestColumn(this.placements);
3061
+ // `autoTickSize`: half the tallest mark at a given fit - a hovered dot (its growth isn't
3062
+ // scaled) or an image's box - toward the x axis.
3063
+ const markHalf = (fit) => Math.max(hasDots ? dotRadius * fit + DOT_HOVER_GROWTH : 0, hasImages ? this.pointImage.maxHeight * fit / 2 : 0);
3064
+ // The fit shrinks marks to the plot's height, which an auto tick takes its length out of, so
3065
+ // with `autoTickSize` the layout is settled in up to three passes: at full size; at the size
3066
+ // that fit, if smaller; and - should the height that handed back have grown the marks past
3067
+ // that, rounding up a pixel - at the length they now need, which is still no longer than the
3068
+ // first, so the marks can only shrink again and never outgrow the tick.
3069
+ let tick = markHalf(1);
3070
+ for (let pass = 0;; pass++) {
3071
+ if (!this.layout(chartElm, config, tick, fullSize)) {
3072
+ return;
3073
+ }
3074
+ const fit = tallest ? Math.min(1, this.height / (tallest * (fullSize + gap))) : 1;
3075
+ this.markSize = fullSize * fit;
3076
+ this.markGap = gap * fit;
3077
+ this.dotRadius = dotRadius * fit;
3078
+ const needed = Math.ceil(markHalf(fit));
3079
+ if (!this.xAxis.autoTickSize || this.xAxis.hide || needed === this.xAxis.tickSize || pass === 2) {
3080
+ break;
3081
+ }
3082
+ tick = needed;
3041
3083
  }
3042
3084
  this.ensureColorCount(config.data.length);
3043
3085
  this.applyColorOverride(config.colorOverride);
3044
- // Shrink every mark evenly when the tallest column wouldn't fit the plot's height.
3045
- const tallest = tallestColumn(this.placements);
3046
- const fit = tallest ? Math.min(1, this.height / (tallest * (fullSize + gap))) : 1;
3047
- this.markSize = fullSize * fit;
3048
- this.markGap = gap * fit;
3049
- this.dotRadius = dotRadius * fit;
3050
3086
  this.xScale = this.buildXScale(rawXAxis?.domainMin, rawXAxis?.domainMax);
3051
3087
  this.drawChart(chartElm);
3052
3088
  }
3089
+ /**
3090
+ * Sets the axes and margins up and measures the plot area, with `tick` as the x axis's length
3091
+ * under `autoTickSize`. Returns `initializeChartState`'s result. On a copy of the config each
3092
+ * time: initializeAxisState() rewrites `height`, which mustn't reach the consumer's object or
3093
+ * build up over passes.
3094
+ */
3095
+ layout(chartElm, config, tick, fullSize) {
3096
+ config = { ...config };
3097
+ this.initializeAxisState(config, 'x', 0, { x: tick, y: 0 });
3098
+ // A mark at the domain's edge is centered on it, so half of it hangs past the plot area.
3099
+ const half = Math.ceil(fullSize / 2);
3100
+ this.reserveEdgeSpace({ left: half, right: half });
3101
+ return this.initializeChartState(chartElm, config);
3102
+ }
3053
3103
  /**
3054
3104
  * The value axis: `xAxis.domainMin` / `domainMax` where given, otherwise the data's extent
3055
3105
  * rounded out to nice ticks - checked on the consumer's own axis config, since the resolved one
@@ -4097,12 +4147,12 @@ class PlaChartBuilder extends PcacChart {
4097
4147
  /**
4098
4148
  * How far the points' clip-path rect extends past the drawable [0, width] x [0, height] area on
4099
4149
  * every side, so a point sitting exactly on the domain's edge isn't cut in half. 10px
4100
- * comfortably clears a dot (r = 4, or 6 on hover); a point image can be much bigger than that,
4101
- * so buildChart() widens this to half the largest image dimension whenever any point has one
4102
- * (and grows the margins to match - see `reservePointSpace()` - since the clip-path only
4103
- * matters up to the edge of the SVG). The buffer is only there for points whose center is
4104
- * inside the plot; one whose center zoom has carried past an edge is hidden outright (see
4105
- * `pointVisible`), rather than left showing up to a whole half-mark beyond the axis.
4150
+ * comfortably clears a dot (r = 4, or 6 on hover); a point image or a gauge ring can be much
4151
+ * bigger than that, so `reservePointSpace()` widens this to half the largest mark on the chart
4152
+ * (and grows the margins to match, since the clip-path only matters up to the edge of the SVG).
4153
+ * The buffer is only there for points whose center is inside the plot; one whose center zoom
4154
+ * has carried past an edge is hidden outright (see `pointVisible`), rather than left showing up
4155
+ * to a whole half-mark beyond the axis.
4106
4156
  */
4107
4157
  clipBuffer = 10;
4108
4158
  pointImage;
@@ -4147,11 +4197,13 @@ class PlaChartBuilder extends PcacChart {
4147
4197
  hide: false,
4148
4198
  data: []
4149
4199
  }));
4200
+ // Before the axes and the layout: the marks' size feeds `autoTickSize`, and a ring widens what
4201
+ // fan-out and the edge space have to make room for.
4202
+ this.pointImage = { ...new PcacPointImageConfig(), ...this.config.pointImage };
4203
+ this.pointGauge = this.config.pointGauge ? { ...new PcacPointGaugeConfig(), ...this.config.pointGauge } : null;
4150
4204
  // A hidden axis keeps 8px rather than 0 so a dot on the edge of the plot isn't clipped
4151
- this.initializeAxisState(this.config, 'y', 8);
4205
+ this.initializeAxisState(this.config, 'y', 8, this.largestMarkHalf());
4152
4206
  this.chartTypeLabel = CHART_TYPE_LABELS[type];
4153
- // Before the layout: a ring widens what fan-out and the edge space have to make room for.
4154
- this.pointGauge = this.config.pointGauge ? { ...new PcacPointGaugeConfig(), ...this.config.pointGauge } : null;
4155
4207
  this.resolvePointLayout(type);
4156
4208
  this.reservePointSpace();
4157
4209
  this.pointRange = this.config.pointRange ? { ...new PcacPointRangeConfig(), ...this.config.pointRange } : null;
@@ -4290,13 +4342,12 @@ class PlaChartBuilder extends PcacChart {
4290
4342
  this.restoreTabStop(chartElm);
4291
4343
  }
4292
4344
  /**
4293
- * Resolves `pointImage`, finds the points that share a coordinate and, on a plot chart with
4345
+ * Finds the points that share a coordinate and, on a plot chart with
4294
4346
  * `pointFanOut`, works out where to draw each of them instead. Coincidence is found from the
4295
4347
  * data (see `findCoincidentGroups`) so this can run before the scales exist. Line and area
4296
4348
  * charts still get the groups, for the tooltip's `coincident` list, but never an offset.
4297
4349
  */
4298
4350
  resolvePointLayout(type) {
4299
- this.pointImage = { ...new PcacPointImageConfig(), ...this.config.pointImage };
4300
4351
  this.coincidentGroups = findCoincidentGroups(this.config.data, this.xAxis.format);
4301
4352
  this.coincidentOf = new Map(this.coincidentGroups.flatMap((group) => group.members.map((member) => [member.data, group])));
4302
4353
  const fanOut = type === PcacLineAreaPlotChartConfigType.Plot
@@ -4318,26 +4369,51 @@ class PlaChartBuilder extends PcacChart {
4318
4369
  this.fanOutOffsets = fanOutOffsets(this.coincidentGroups, radius);
4319
4370
  }
4320
4371
  /**
4321
- * When any point has an `image`, makes room for it at the edge of the domain: the clip-path
4322
- * buffer grows to half the box so the `.dots` group lets it through, and the margins grow to at
4323
- * least that same amount so the `<svg>` doesn't cut off what the clip-path let through (an image
4324
- * box is centered on its point, so at the top of the y domain half of it sits above the plot
4325
- * area - in `margin.top`, which is only 8px by default). Half the box is all a fan-out needs
4326
- * too: a fanned-out ring is shifted back inside the plot area (`fanOutShift`), so no member's
4327
- * center ever sits past the edge either. Must run after `resolvePointLayout()` and between
4328
- * `initializeAxisState()` and `initializeChartState()`, see `reserveEdgeSpace`.
4372
+ * Half the largest mark on the chart toward each axis, for `autoTickSize` and the edge space
4373
+ * (`reservePointSpace`): `x` its vertical half (what reaches down to the x axis), `y` its
4374
+ * horizontal half. Measured as drawn - a hovered dot (`GAUGE_DOT_RADIUS`), an image's box, and
4375
+ * a gauge ring around either (circular, so the same both ways). Points in a hidden series
4376
+ * count, so toggling one in a legend doesn't move the axes; a gap (no value) draws nothing and
4377
+ * doesn't. Needs `pointImage` and `pointGauge` resolved.
4329
4378
  */
4330
- reservePointSpace() {
4331
- const points = this.config.data.flatMap((series) => series.data);
4332
- const hasImages = points.some((point) => !!point.image);
4333
- // A gauge ring reaches past its mark on every side, so it needs the same room the mark does.
4334
- const ring = this.pointGauge && points.some(hasGauge) ? Math.ceil(gaugeExtent(this.pointGauge)) : 0;
4335
- if (!hasImages && !ring) {
4336
- this.clipBuffer = 10;
4337
- return;
4379
+ largestMarkHalf() {
4380
+ const { maxWidth, maxHeight } = this.pointImage;
4381
+ const half = { x: 0, y: 0 };
4382
+ for (const point of this.config.data.flatMap((series) => series.data ?? [])) {
4383
+ if (!hasValue(point)) {
4384
+ continue;
4385
+ }
4386
+ let x = point.image ? maxHeight / 2 : GAUGE_DOT_RADIUS;
4387
+ let y = point.image ? maxWidth / 2 : GAUGE_DOT_RADIUS;
4388
+ if (this.pointGauge && hasGauge(point)) {
4389
+ // The ring surrounds the mark's larger side - see `markRadius` in `drawDots`.
4390
+ const ring = (point.image ? Math.max(maxWidth, maxHeight) / 2 : GAUGE_DOT_RADIUS) + gaugeExtent(this.pointGauge);
4391
+ x = Math.max(x, ring);
4392
+ y = Math.max(y, ring);
4393
+ }
4394
+ half.x = Math.max(half.x, x);
4395
+ half.y = Math.max(half.y, y);
4338
4396
  }
4339
- const halfWidth = (hasImages ? Math.ceil(this.pointImage.maxWidth / 2) : GAUGE_DOT_RADIUS) + ring;
4340
- const halfHeight = (hasImages ? Math.ceil(this.pointImage.maxHeight / 2) : GAUGE_DOT_RADIUS) + ring;
4397
+ return half;
4398
+ }
4399
+ /**
4400
+ * Makes room for the points at the edge of the domain: the clip-path buffer grows to half the
4401
+ * largest mark (`largestMarkHalf()` - an image box, a ring, or a hovered dot) so the `.dots`
4402
+ * group lets it through, and the margins grow to at least that same amount so the `<svg>`
4403
+ * doesn't cut off what the clip-path let through (a mark is centered on its point, so at the top
4404
+ * of the y domain half of it sits above the plot area - in `margin.top`, which is only 8px by
4405
+ * default). A ring is measured around the image box's larger side, as `drawDots` draws it, on
4406
+ * both axes; measured against the box's own side, a ringed wide image at the top of the domain
4407
+ * had the top of its ring cut off by the SVG. Half a mark is all a fan-out needs too: a
4408
+ * fanned-out ring is shifted back inside the plot area (`fanOutShift`), so no member's center
4409
+ * ever sits past the edge either. A plain dot fits the default 10px buffer and every margin
4410
+ * already. Must run after `resolvePointLayout()` and between `initializeAxisState()` and
4411
+ * `initializeChartState()`, see `reserveEdgeSpace`.
4412
+ */
4413
+ reservePointSpace() {
4414
+ const half = this.largestMarkHalf();
4415
+ const halfWidth = Math.ceil(half.y);
4416
+ const halfHeight = Math.ceil(half.x);
4341
4417
  this.clipBuffer = Math.max(10, halfWidth, halfHeight);
4342
4418
  this.reserveEdgeSpace({ top: halfHeight, bottom: halfHeight, left: halfWidth, right: halfWidth });
4343
4419
  }