@pioneer-code/pioneer-charts 22.2.25 → 22.2.26

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/README.md CHANGED
@@ -28,6 +28,10 @@ Each chart has its own page with live examples, markup and its full configuratio
28
28
 
29
29
  Or see them all together on the [chart examples](https://pioneercharts.com/charts) page.
30
30
 
31
+ ## Built with Pioneer Charts
32
+
33
+ - [Down Lane Motion](https://downlanemotion.com) - a bowling ball catalog whose reaction, tech specs, look-alike, arsenal ladder and stats pages are all Pioneer Charts plot, proximity, dot plot, bar and donut charts.
34
+
31
35
  ## Features
32
36
 
33
37
  - Bar (vertical and horizontal), line, area, plot, pie, donut, dot plot and proximity charts, plus a legend.
@@ -156,6 +156,10 @@ class PcacAxisConfig {
156
156
  * y axis they run bottom-to-top like the label, `min` at the bottom. The margin grows by
157
157
  * `PcacChart.AXIS_SUB_LABEL_SPACE` when any is set, shrinking the plot area. Not drawn on a
158
158
  * hidden axis. Styled by the theme's `.pcac-axis-sub-label` rule.
159
+ *
160
+ * On a zoomable line/area/plot axis each stands for the value at its spot on the unzoomed axis
161
+ * and moves with it. Zoomed out of view, the nearest on each side is pinned to that end with an
162
+ * arrow toward its value (`.pcac-axis-sub-label-out-of-view`, dimmed by the theme).
159
163
  */
160
164
  subLabels;
161
165
  /** `subLabels` color, all three (`--pcac-axis-sub-label-color`). Theme default `$gray-600`. */
@@ -404,6 +408,11 @@ function valueTickFormat(pcacFormat, scale, ticks) {
404
408
  }
405
409
  }
406
410
 
411
+ /** The arrows on a sub label pinned to the start (bottom / left) or end of its axis. */
412
+ const PCAC_SUB_LABEL_BEFORE = '◂ ';
413
+ const PCAC_SUB_LABEL_AFTER = ' ▸';
414
+ /** How far, in px, a sub label may sit past an end of its axis and still count as on it. */
415
+ const SUB_LABEL_EDGE_TOLERANCE = 0.5;
407
416
  class PcacAxisBuilder {
408
417
  drawAxis(config) {
409
418
  this.drawXAxis(config);
@@ -444,7 +453,10 @@ class PcacAxisBuilder {
444
453
  .classed('pcac-axis-line', config.yAxis.showLine)
445
454
  .call(yAxis)
446
455
  .call(applyColors, config.yAxis);
447
- this.drawLabels(group, config.yAxis, { length: config.height, outer: config.margin.left, vertical: true });
456
+ this.drawLabels(group, config.yAxis, {
457
+ length: config.height, outer: config.margin.left, vertical: true,
458
+ scale: config.yScale, subLabelScale: config.ySubLabelScale ?? config.yScale,
459
+ });
448
460
  }
449
461
  drawXAxis(config) {
450
462
  if (config.xAxis.hide)
@@ -467,7 +479,10 @@ class PcacAxisBuilder {
467
479
  .attr('transform', 'translate(0,' + config.height + ')')
468
480
  .call(xAxis)
469
481
  .call(applyColors, config.xAxis);
470
- this.drawLabels(group, config.xAxis, { length: config.width, outer: config.margin.bottom, vertical: false });
482
+ this.drawLabels(group, config.xAxis, {
483
+ length: config.width, outer: config.margin.bottom, vertical: false,
484
+ scale: config.xScale, subLabelScale: config.xSubLabelScale ?? config.xScale,
485
+ });
471
486
  }
472
487
  /**
473
488
  * The axis `label` and `subLabels`. Both are placed by two distances: along the axis (0 at its
@@ -477,32 +492,68 @@ class PcacAxisBuilder {
477
492
  * to read bottom-to-top, which swaps the two: after `rotate(-90)` x runs up the axis (so the
478
493
  * bottom is x = -length) and y runs left. `fill` is set explicitly because d3-axis puts
479
494
  * `fill="none"` on the group; its own tick text does the same.
495
+ *
496
+ * Sub labels name values, not spots on the screen: each stands for the value at the start,
497
+ * middle or end of `subLabelScale` and is drawn where `scale` puts it (`subLabelPlacements`), so
498
+ * on a zoomed axis it moves with its value. Unzoomed the two scales are the same and the labels
499
+ * sit at the start, middle and end. One on the axis is anchored inside it: `start` at the start,
500
+ * `end` at the end, otherwise centered and kept from spilling past either end. One zoomed out of
501
+ * view isn't dropped: the nearest on each side is pinned to that end, dimmed
502
+ * (`pcac-axis-sub-label-out-of-view`) and with an arrow pointing the way to its value - unless
503
+ * it would cover a label that's in view, which says more.
480
504
  */
481
505
  drawLabels(group, axis, layout) {
482
- const text = (cls, along, out, anchor, content) => {
483
- group.append('text')
484
- .attr('class', cls)
485
- .attr('fill', 'currentColor')
486
- .attr('text-anchor', anchor)
487
- .attr('transform', layout.vertical ? 'rotate(-90)' : null)
488
- .attr('x', layout.vertical ? along - layout.length : along)
489
- .attr('y', layout.vertical ? -out : out)
490
- .attr('dy', layout.vertical ? '1em' : '-0.35em')
491
- .text(content);
492
- };
506
+ const { length } = layout;
507
+ const text = (cls, along, out, anchor, content) => group.append('text')
508
+ .attr('class', cls)
509
+ .attr('fill', 'currentColor')
510
+ .attr('text-anchor', anchor)
511
+ .attr('transform', layout.vertical ? 'rotate(-90)' : null)
512
+ .attr('x', layout.vertical ? along - length : along)
513
+ .attr('y', layout.vertical ? -out : out)
514
+ .attr('dy', layout.vertical ? '1em' : '-0.35em')
515
+ .text(content);
493
516
  if (axis.label) {
494
- text('pcac-axis-label', layout.length / 2, layout.outer, 'middle', axis.label);
517
+ text('pcac-axis-label', length / 2, layout.outer, 'middle', axis.label);
495
518
  }
496
519
  const sub = axis.subLabels;
497
- if (sub) {
498
- const edge = layout.outer - (axis.label ? PCAC_AXIS_LABEL_SPACE : 0);
499
- if (sub.min)
500
- text('pcac-axis-sub-label', 0, edge, 'start', sub.min);
501
- if (sub.mid)
502
- text('pcac-axis-sub-label', layout.length / 2, edge, 'middle', sub.mid);
503
- if (sub.max)
504
- text('pcac-axis-sub-label', layout.length, edge, 'end', sub.max);
505
- }
520
+ if (!sub)
521
+ return;
522
+ const edge = layout.outer - (axis.label ? PCAC_AXIS_LABEL_SPACE : 0);
523
+ const placements = subLabelPlacements(sub, layout);
524
+ const before = placements.filter(p => p.along < -SUB_LABEL_EDGE_TOLERANCE);
525
+ const after = placements.filter(p => p.along > length + SUB_LABEL_EDGE_TOLERANCE);
526
+ const inView = placements.filter(p => !before.includes(p) && !after.includes(p));
527
+ // Each drawn label's extent along the axis, for the pinned ones to check they don't cover it.
528
+ const extents = inView.map(p => {
529
+ if (p.along <= SUB_LABEL_EDGE_TOLERANCE) {
530
+ const w = textLength(text('pcac-axis-sub-label', 0, edge, 'start', p.content));
531
+ return [0, w];
532
+ }
533
+ if (p.along >= length - SUB_LABEL_EDGE_TOLERANCE) {
534
+ const w = textLength(text('pcac-axis-sub-label', length, edge, 'end', p.content));
535
+ return [length - w, length];
536
+ }
537
+ const label = text('pcac-axis-sub-label', p.along, edge, 'middle', p.content);
538
+ const half = textLength(label) / 2;
539
+ const along = half * 2 >= length ? length / 2 : Math.min(Math.max(p.along, half), length - half);
540
+ label.attr('x', layout.vertical ? along - length : along);
541
+ return [along - half, along + half];
542
+ });
543
+ const pin = (p, atEnd) => {
544
+ if (!p)
545
+ return;
546
+ const content = atEnd ? p.content + PCAC_SUB_LABEL_AFTER : PCAC_SUB_LABEL_BEFORE + p.content;
547
+ const label = text('pcac-axis-sub-label pcac-axis-sub-label-out-of-view', atEnd ? length : 0, edge, atEnd ? 'end' : 'start', content);
548
+ const w = textLength(label);
549
+ const [lo, hi] = atEnd ? [length - w, length] : [0, w];
550
+ if (extents.some(([a, b]) => a < hi && b > lo)) {
551
+ label.remove();
552
+ }
553
+ };
554
+ // The nearest out of view on each side: the last before the start, the first past the end.
555
+ pin(before.reduce((n, p) => (!n || p.along > n.along ? p : n), undefined), false);
556
+ pin(after.reduce((n, p) => (!n || p.along < n.along ? p : n), undefined), true);
506
557
  }
507
558
  static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.2.1", ngImport: i0, type: PcacAxisBuilder, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
508
559
  static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "22.2.1", ngImport: i0, type: PcacAxisBuilder, providedIn: 'root' });
@@ -513,6 +564,31 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.2.1", ngImpor
513
564
  providedIn: 'root',
514
565
  }]
515
566
  }] });
567
+ /**
568
+ * Where each given sub label goes along the axis (px from its start; the bottom, for y). Its value
569
+ * is read off `subLabelScale` at the start, middle or end of the axis and put back through
570
+ * `scale`. A scale without `invert` (a band scale's categories) has no value between its ends, so
571
+ * there the labels simply keep the start, middle and end - such an axis never zooms anyway.
572
+ */
573
+ function subLabelPlacements(sub, layout) {
574
+ const { length, vertical, scale } = layout;
575
+ const base = layout.subLabelScale;
576
+ // The y axis's along runs bottom-up, its pixels top-down.
577
+ const flip = (px) => (vertical ? length - px : px);
578
+ const spots = [['min', 0], ['mid', length / 2], ['max', length]];
579
+ return spots
580
+ .filter(([key]) => !!sub[key])
581
+ .map(([key, along]) => ({
582
+ key,
583
+ content: sub[key],
584
+ along: base.invert ? flip(scale(base.invert(flip(along))) ?? along) : along,
585
+ }));
586
+ }
587
+ /** A drawn text's length in px; 0 where it can't be measured (jsdom has no SVG text layout). */
588
+ function textLength(label) {
589
+ const node = label.node();
590
+ return typeof node?.getComputedTextLength === 'function' ? node.getComputedTextLength() : 0;
591
+ }
516
592
  /**
517
593
  * Sets the axis's `*Color` fields on its group as CSS custom properties, which the theme reads
518
594
  * with its own color as the fallback (`var(--pcac-axis-tick-color, ...)`). Custom properties
@@ -1336,10 +1412,13 @@ class PcacChart {
1336
1412
  /**
1337
1413
  * The `PcacAxisBuilder` config for this chart's current state - everything but the scales is
1338
1414
  * already on the instance. Builders pass the result to `drawAxis()` (or `drawXAxis()` with a
1339
- * rescaled x, on zoom).
1415
+ * rescaled x, on zoom). A chart that zooms also passes its unzoomed scales as `subLabelScales`,
1416
+ * so the axes' `subLabels` stay with the values they name.
1340
1417
  */
1341
- axisBuilderConfig(xScale, yScale) {
1418
+ axisBuilderConfig(xScale, yScale, subLabelScales) {
1342
1419
  return {
1420
+ xSubLabelScale: subLabelScales?.x,
1421
+ ySubLabelScale: subLabelScales?.y,
1343
1422
  svg: this.svg,
1344
1423
  width: this.width,
1345
1424
  height: this.height,
@@ -2871,16 +2950,25 @@ class PcacReferenceLine {
2871
2950
  }
2872
2951
  /**
2873
2952
  * Text pinned to the plot area's corners (see `PcacLineAreaChartConfig.cornerLabels`) - names for
2874
- * the regions the plot divides into, such as the quadrants between two reference lines. Pinned to
2875
- * the plot's frame rather than to data, so they stay put when the chart is zoomed. Drawn under the
2876
- * series, so a point in the corner covers its label rather than the other way round, unless the
2877
- * chart sets `labelsOnTop`. Any corner left unset is left empty.
2953
+ * the regions the plot divides into, such as the quadrants between two reference lines. Drawn in
2954
+ * the corners of the plot's frame, so they stay put when the chart is zoomed - give `split` to have
2955
+ * each one shown only while its region is still in its corner. Drawn under the series, so a point in
2956
+ * the corner covers its label rather than the other way round, unless the chart sets `labelsOnTop`.
2957
+ * Any corner left unset is left empty.
2878
2958
  */
2879
2959
  class PcacCornerLabels {
2880
2960
  topLeft;
2881
2961
  topRight;
2882
2962
  bottomLeft;
2883
2963
  bottomRight;
2964
+ /**
2965
+ * Where the regions divide, in each axis's own terms (as `PcacReferenceLine.value`): `x` splits
2966
+ * left from right, `y` bottom from top; leave one out for halves. With it, a label is shown only
2967
+ * while its region fills its corner of the view with room for it - zoomed into one quadrant, only
2968
+ * that quadrant's name is left, rather than all four naming points that aren't theirs. Without
2969
+ * it the labels are always shown.
2970
+ */
2971
+ split;
2884
2972
  /**
2885
2973
  * Any CSS color for all four. Theme default `$gray-600`. Applied as `--pcac-corner-label-color`
2886
2974
  * on their group, so a stylesheet can set it on an ancestor instead (a config value wins).
@@ -3886,9 +3974,13 @@ const CORNER_INSET = 8;
3886
3974
  * way a point's `key` is under the axis's format (see `getXFormat`).
3887
3975
  */
3888
3976
  function referenceLinePosition(line, scales, xFormat) {
3889
- const position = line.axis === 'x'
3890
- ? scales.x(xFormat === PcacFormatEnum.DateTime ? new Date(line.value) : Number(line.value))
3891
- : scales.y(Number(line.value));
3977
+ return valuePosition(line.axis, line.value, scales, xFormat);
3978
+ }
3979
+ /** Where `value` sits on `axis`, in plot pixels, or `null` when it doesn't place. */
3980
+ function valuePosition(axis, value, scales, xFormat) {
3981
+ const position = axis === 'x'
3982
+ ? scales.x(xFormat === PcacFormatEnum.DateTime ? new Date(value) : Number(value))
3983
+ : scales.y(Number(value));
3892
3984
  return Number.isFinite(position) ? position : null;
3893
3985
  }
3894
3986
  /**
@@ -3956,18 +4048,18 @@ function positionReferenceLines(svg, scales, xFormat, width, height) {
3956
4048
  }
3957
4049
  /**
3958
4050
  * Draws `labels` into a `.corner-labels` group, each a `.corner-label` inset from its corner of
3959
- * the plot area. Pinned to the frame, so zoom leaves them alone. Hidden from screen readers, as
3960
- * the grid is.
4051
+ * the plot area, then shows or hides them for the current view (`positionCornerLabels`). Hidden
4052
+ * from screen readers, as the grid is.
3961
4053
  */
3962
- function drawCornerLabels(svg, labels, width, height) {
4054
+ function drawCornerLabels(svg, labels, scales, xFormat, width, height) {
3963
4055
  if (!labels) {
3964
4056
  return;
3965
4057
  }
3966
4058
  const corners = [
3967
- { text: labels.topLeft, x: CORNER_INSET, y: CORNER_INSET, anchor: 'start', baseline: 'hanging', name: 'top-left' },
3968
- { text: labels.topRight, x: width - CORNER_INSET, y: CORNER_INSET, anchor: 'end', baseline: 'hanging', name: 'top-right' },
3969
- { text: labels.bottomLeft, x: CORNER_INSET, y: height - CORNER_INSET, anchor: 'start', baseline: 'auto', name: 'bottom-left' },
3970
- { text: labels.bottomRight, x: width - CORNER_INSET, y: height - CORNER_INSET, anchor: 'end', baseline: 'auto', name: 'bottom-right' },
4059
+ { text: labels.topLeft, left: true, top: true, x: CORNER_INSET, y: CORNER_INSET, anchor: 'start', baseline: 'hanging', name: 'top-left' },
4060
+ { text: labels.topRight, left: false, top: true, x: width - CORNER_INSET, y: CORNER_INSET, anchor: 'end', baseline: 'hanging', name: 'top-right' },
4061
+ { text: labels.bottomLeft, left: true, top: false, x: CORNER_INSET, y: height - CORNER_INSET, anchor: 'start', baseline: 'auto', name: 'bottom-left' },
4062
+ { text: labels.bottomRight, left: false, top: false, x: width - CORNER_INSET, y: height - CORNER_INSET, anchor: 'end', baseline: 'auto', name: 'bottom-right' },
3971
4063
  ].filter((corner) => !!corner.text);
3972
4064
  if (corners.length === 0) {
3973
4065
  return;
@@ -3985,6 +4077,50 @@ function drawCornerLabels(svg, labels, width, height) {
3985
4077
  .attr('text-anchor', (corner) => corner.anchor)
3986
4078
  .attr('dominant-baseline', (corner) => corner.baseline)
3987
4079
  .text((corner) => corner.text);
4080
+ positionCornerLabels(svg, labels, scales, xFormat, width, height);
4081
+ }
4082
+ /**
4083
+ * Shows each corner label only while its region of `labels.split` fills its corner of the view
4084
+ * with room for the label and its inset - on the first draw and again on every zoom. The labels
4085
+ * themselves never move: a region still in view always reaches its own corner of the plot, so
4086
+ * there's nowhere else to put one, only whether it's still true there. Without a `split` every
4087
+ * label is shown, as it always was.
4088
+ */
4089
+ function positionCornerLabels(svg, labels, scales, xFormat, width, height) {
4090
+ const split = labels?.split;
4091
+ if (!split) {
4092
+ return;
4093
+ }
4094
+ // The split in plot pixels, clamped to the plot; an axis without one (or one that won't place)
4095
+ // isn't split.
4096
+ const at = (axis, length) => {
4097
+ const value = split[axis];
4098
+ const position = value === undefined ? null : valuePosition(axis, value, scales, xFormat);
4099
+ return position === null ? null : Math.min(Math.max(position, 0), length);
4100
+ };
4101
+ const sx = at('x', width);
4102
+ const sy = at('y', height);
4103
+ svg.selectAll('.corner-label')
4104
+ .attr('display', function (corner) {
4105
+ // y pixels run top-down, so the top region is the one above the split.
4106
+ const w = sx === null ? width : corner.left ? sx : width - sx;
4107
+ const h = sy === null ? height : corner.top ? sy : height - sy;
4108
+ const size = labelSize(this);
4109
+ return w > 0 && h > 0 && w >= size.width + 2 * CORNER_INSET && h >= size.height + 2 * CORNER_INSET ? null : 'none';
4110
+ });
4111
+ }
4112
+ /** A drawn label's size in px; 0 by 0 where it can't be measured (jsdom has no SVG layout). */
4113
+ function labelSize(label) {
4114
+ if (typeof label.getBBox !== 'function') {
4115
+ return { width: 0, height: 0 };
4116
+ }
4117
+ // A hidden label measures 0 by 0, so it's shown for the measurement.
4118
+ const display = label.getAttribute('display');
4119
+ label.removeAttribute('display');
4120
+ const { width, height } = label.getBBox();
4121
+ if (display !== null)
4122
+ label.setAttribute('display', display);
4123
+ return { width, height };
3988
4124
  }
3989
4125
  /**
3990
4126
  * With `labelsOnTop`, moves the corner labels and reference-line labels above everything drawn
@@ -4269,12 +4405,12 @@ class PlaChartBuilder extends PcacChart {
4269
4405
  // is redrawn against the rescaled scale and dropped back underneath everything (append
4270
4406
  // puts it on top).
4271
4407
  if (this.config.enableZoomX) {
4272
- this.axisBuilder.drawXAxis(this.axisBuilderConfig(newX, newY));
4408
+ this.axisBuilder.drawXAxis(this.axisBuilderConfig(newX, newY, this.baseScales));
4273
4409
  this.svg.selectAll('.pcac-grid-vertical').remove();
4274
4410
  this.drawGrids(newX, newY, 'x');
4275
4411
  }
4276
4412
  if (this.config.enableZoomY) {
4277
- this.axisBuilder.drawYAxis(this.axisBuilderConfig(newX, newY));
4413
+ this.axisBuilder.drawYAxis(this.axisBuilderConfig(newX, newY, this.baseScales));
4278
4414
  this.svg.selectAll('.pcac-grid-horizontal').remove();
4279
4415
  this.drawGrids(newX, newY, 'y');
4280
4416
  }
@@ -4308,8 +4444,9 @@ class PlaChartBuilder extends PcacChart {
4308
4444
  .attr('x2', (member) => this.spokeEnd(member, zoomedScales).dx)
4309
4445
  .attr('y2', (member) => this.spokeEnd(member, zoomedScales).dy);
4310
4446
  // Reference lines sit at data values, so they move with it; corner labels are pinned to the
4311
- // frame and stay put.
4447
+ // frame and stay put, but one whose region of `split` has left its corner is hidden.
4312
4448
  positionReferenceLines(this.svg, zoomedScales, this.xAxis.format, this.width, this.height);
4449
+ positionCornerLabels(this.svg, this.config.cornerLabels, zoomedScales, this.xAxis.format, this.width, this.height);
4313
4450
  // The hover crosshair positions and labels against the scales, so it takes the zoomed ones.
4314
4451
  if (this.effectsEnabled) {
4315
4452
  this.effectsBuilder.updateScales(newX, newY);
@@ -4337,10 +4474,10 @@ class PlaChartBuilder extends PcacChart {
4337
4474
  this.buildContainer(chartElm);
4338
4475
  this.attachZoomBehavior();
4339
4476
  this.createReusableClipPath();
4340
- this.axisBuilder.drawAxis(this.axisBuilderConfig(this.scales.x, this.scales.y));
4477
+ this.axisBuilder.drawAxis(this.axisBuilderConfig(this.scales.x, this.scales.y, this.baseScales));
4341
4478
  this.drawGrids(this.scales.x, this.scales.y);
4342
4479
  // Over the grid, under the series: guides, not data.
4343
- drawCornerLabels(this.svg, config.cornerLabels, this.width, this.height);
4480
+ drawCornerLabels(this.svg, config.cornerLabels, this.scales, this.xAxis.format, this.width, this.height);
4344
4481
  drawReferenceLines(this.svg, config.referenceLines, this.scales, this.xAxis.format, this.width, this.height, this.plotClipPathId);
4345
4482
  this.drawLineArea(config, type);
4346
4483
  this.effectsEnabled = !!config.enableEffects && type !== PcacLineAreaPlotChartConfigType.Plot;