@pioneer-code/pioneer-charts 22.2.0 → 22.2.2

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/package.json CHANGED
@@ -22,7 +22,7 @@
22
22
  "type": "git",
23
23
  "url": "git+https://github.com/PioneerCode/pioneer-charts.git"
24
24
  },
25
- "version": "22.2.0",
25
+ "version": "22.2.2",
26
26
  "license": "MIT",
27
27
  "peerDependencies": {
28
28
  "@angular/common": "^22.1.0",
@@ -10,6 +10,18 @@
10
10
  stroke-width: 2px;
11
11
  }
12
12
 
13
+ // The plot chart's `pointFanOut` anchors (see PcacPointFanOutConfig.showAnchor): a spoke from
14
+ // the shared coordinate to each fanned-out point, and a dot on the coordinate itself. Quiet
15
+ // grays, like the grid, so they read as guides rather than data.
16
+ .fan-out-spoke {
17
+ stroke: imports.$gray-400;
18
+ stroke-width: 1px;
19
+ }
20
+
21
+ .fan-out-anchor {
22
+ fill: imports.$gray-600;
23
+ }
24
+
13
25
  .effects-canvas {
14
26
  fill: none;
15
27
  }
@@ -105,6 +105,25 @@ declare class PcacAxisConfig {
105
105
  * hidden axis. Styled by the theme's `.pcac-axis-sub-label` rule.
106
106
  */
107
107
  subLabels?: PcacAxisSubLabels;
108
+ /**
109
+ * How the values along this axis are interpreted and shown - the tick labels, and the value
110
+ * (`yAxis`) or key (`xAxis`) in the default tooltip. On the line/area/plot charts the x axis's
111
+ * format is also what decides how a point's `key` maps to an x position (by index for the
112
+ * default, `Decimal` and `DateTime` by the key's own value on a linear/time scale - see
113
+ * `PcacLineAreaChartConfig`); a bar chart's category axis ignores it. Default `None`, which
114
+ * on those charts behaves as `DatasetLength`.
115
+ */
116
+ format?: PcacFormatEnum;
117
+ /**
118
+ * The value axis's domain: it runs from `domainMin` to `domainMax`, ignoring the data. Defaults
119
+ * 0 and 100. Only the type of axis that has a domain to set reads them - a bar chart's category
120
+ * axis ignores both, its value axis reads `domainMax` only (bars always grow from 0), and a
121
+ * line/area/plot chart's x axis reads them only under the `Decimal` (numbers) and `DateTime`
122
+ * (anything `new Date()` accepts, and required) formats - the index-based formats size the
123
+ * axis from the data.
124
+ */
125
+ domainMin?: number | string;
126
+ domainMax?: number | string;
108
127
  }
109
128
  /**
110
129
  * The `PcacChartMargin` type lives here rather than in chart.ts so the axis builder can take
@@ -182,10 +201,8 @@ declare enum PcacFormatEnum {
182
201
  }
183
202
 
184
203
  declare class PcacBarHorizontalChartConfig extends PcacAxisChartConfig {
185
- domainMax: number;
186
204
  isStacked: boolean;
187
205
  thresholds: PcacData[];
188
- tickFormat: PcacFormatEnum;
189
206
  spreadColorsPerGroup: boolean;
190
207
  colorOverride: PcacBarHorizontalChartColorOverrideConfig;
191
208
  }
@@ -218,11 +235,10 @@ interface IPcacAxisBuilderConfig<XDomain extends AxisDomain = AxisDomain, YDomai
218
235
  * D3's default 6px outer end-caps (`tickSizeOuter`), so it reads as a bracket rather than a
219
236
  * bare rule; that's D3's standard look and is left as-is. `label` and `subLabels` are drawn
220
237
  * inside the axis group (so they're raised and non-interactive along with it) - see `drawLabels`.
238
+ * `format` picks the tick label format; `None` leaves D3's default.
221
239
  */
222
240
  xAxis: PcacResolvedAxisConfig;
223
241
  yAxis: PcacResolvedAxisConfig;
224
- yFormat?: PcacFormatEnum;
225
- xFormat?: PcacFormatEnum;
226
242
  }
227
243
  declare class PcacAxisBuilder {
228
244
  drawAxis<XDomain extends AxisDomain, YDomain extends AxisDomain>(config: IPcacAxisBuilderConfig<XDomain, YDomain>): void;
@@ -327,6 +343,17 @@ declare class PcacTransitionService {
327
343
  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
328
344
  }
329
345
 
346
+ /**
347
+ * A datum drawn at the same coordinate as the hovered one (see `PcacTooltipContext.coincident`),
348
+ * located the same way the context locates `$implicit`: `parent` is the series it belongs to,
349
+ * `index` its position in `parent.data`, `parentIndex` the series' position in the chart's `data`.
350
+ */
351
+ interface PcacTooltipCoincident {
352
+ data: PcacData;
353
+ parent: PcacData;
354
+ index: number;
355
+ parentIndex: number;
356
+ }
330
357
  /**
331
358
  * Template context handed to a consumer's `<ng-template pcacTooltip>` each time a tooltip is shown.
332
359
  */
@@ -364,6 +391,14 @@ interface PcacTooltipContext {
364
391
  * Position of `parent` in the chart's top-level `data`; `null` whenever `parent` is.
365
392
  */
366
393
  parentIndex: number | null;
394
+ /**
395
+ * Every *other* datum drawn at exactly the same coordinate as `$implicit`, in data order, so a
396
+ * template can list who else is at the hovered point. Set by the line, area and plot charts,
397
+ * whether or not the plot chart's `pointFanOut` has spread the points apart (without it, the
398
+ * hovered point is the only one of them visible, which makes this list all the more useful).
399
+ * Empty on the other charts and whenever nothing shares the point.
400
+ */
401
+ coincident: PcacTooltipCoincident[];
367
402
  }
368
403
  /**
369
404
  * Marks an `<ng-template>` projected into any chart component as that chart's tooltip. When
@@ -389,6 +424,17 @@ interface PcacTooltipContext {
389
424
  * <div class="my-tooltip">{{ orders[g!][i].customer }}: {{ point.value | number }}</div>
390
425
  * </ng-template>
391
426
  * ```
427
+ *
428
+ * `coincident` lists the other points at the hovered coordinate, each located the same way:
429
+ *
430
+ * ```html
431
+ * <ng-template pcacTooltip let-point let-others="coincident">
432
+ * <div class="my-tooltip">
433
+ * {{ point.key }}, {{ point.value }}
434
+ * @for (other of others; track other.parentIndex) { <div>Also here: {{ other.parent.key }}</div> }
435
+ * </div>
436
+ * </ng-template>
437
+ * ```
392
438
  */
393
439
  declare class PcacTooltipDirective {
394
440
  readonly templateRef: TemplateRef<PcacTooltipContext>;
@@ -454,6 +500,8 @@ interface PcacTooltipOptions {
454
500
  /** See `PcacTooltipContext.parentIndex`. Defaults to `null`, matching `parent`'s default. */
455
501
  parentIndex?: number | null;
456
502
  isThreshold?: boolean;
503
+ /** See `PcacTooltipContext.coincident`. Defaults to none. */
504
+ coincident?: PcacTooltipCoincident[];
457
505
  valueFormat?: PcacFormatEnum;
458
506
  keyFormat?: PcacFormatEnum;
459
507
  }
@@ -499,11 +547,13 @@ declare class PcacChart {
499
547
  private lastContainerHeight;
500
548
  private lastHeightFull;
501
549
  /**
502
- * How much `initializeAxisState()` last added to `margin.bottom` for tick marks and axis
503
- * labels (negative when a short tick took some away). `resolveHeight()` subtracts it from the
504
- * plot height so the SVG's total height doesn't change with either. Reset alongside the margins.
550
+ * How much the vertical margins have grown this build beyond their defaults - for tick marks
551
+ * and axis labels (`initializeAxisState()`; negative when a short tick took some away) and for
552
+ * content that hangs past the plot's edge (`reserveEdgeSpace()`). `resolveHeight()` subtracts
553
+ * it from the plot height so the SVG's total height doesn't change with any of them. Reset
554
+ * alongside the margins.
505
555
  */
506
- private reservedTickHeight;
556
+ private reservedHeight;
507
557
  /**
508
558
  * Resolves the consumer's projected `<ng-template pcacTooltip>`, if any. Each chart component
509
559
  * points this at its own `contentChild(PcacTooltipDirective)` query. It's a getter rather than
@@ -545,11 +595,11 @@ declare class PcacChart {
545
595
  */
546
596
  initializeAxisState(config: PcacAxisChartConfig, defaultGrid: 'x' | 'y', hiddenAxisMargin?: number): void;
547
597
  /**
548
- * The `PcacAxisBuilder` config for this chart's current state - everything but the scales and
549
- * formats is already on the instance. Builders pass the result to `drawAxis()` (or `drawXAxis()`
550
- * with a rescaled x, on zoom).
598
+ * The `PcacAxisBuilder` config for this chart's current state - everything but the scales is
599
+ * already on the instance. Builders pass the result to `drawAxis()` (or `drawXAxis()` with a
600
+ * rescaled x, on zoom).
551
601
  */
552
- axisBuilderConfig<XDomain extends AxisDomain, YDomain extends AxisDomain>(xScale: AxisScale<XDomain>, yScale: AxisScale<YDomain>, xFormat?: PcacFormatEnum, yFormat?: PcacFormatEnum): IPcacAxisBuilderConfig<XDomain, YDomain>;
602
+ axisBuilderConfig<XDomain extends AxisDomain, YDomain extends AxisDomain>(xScale: AxisScale<XDomain>, yScale: AxisScale<YDomain>): IPcacAxisBuilderConfig<XDomain, YDomain>;
553
603
  /**
554
604
  * Draws whichever grids the resolved axes ask for: vertical lines from the x axis's ticks,
555
605
  * horizontal from the y's (`PcacAxisConfig.showGrid`). `which` restricts it to one axis - the
@@ -568,7 +618,7 @@ declare class PcacChart {
568
618
  * Horizontally that happens on its own: `initializeChartState()` derives `width` from the
569
619
  * container minus the margins. Vertically it doesn't - `config.height` is the plot area, and
570
620
  * the SVG is that plus the margins - so a taller bottom margin would grow the SVG instead. The
571
- * delta is therefore also remembered in `reservedTickHeight` and taken back out of the plot
621
+ * delta is therefore also remembered in `reservedHeight` and taken back out of the plot
572
622
  * height by `resolveHeight()`, keeping the chart's total footprint where the consumer put it.
573
623
  *
574
624
  * Called by `initializeAxisState()` right after `resetMargin()`, for the axes that will be
@@ -578,6 +628,24 @@ declare class PcacChart {
578
628
  * @param yTickSize `tickSizeInner` for the left (y) axis, which lives in `margin.left`
579
629
  */
580
630
  reserveTickSizeMargins(xTickSize?: number, yTickSize?: number): void;
631
+ /**
632
+ * Makes sure each given margin is at least that big, for content drawn at the very edge of the
633
+ * plot area that reaches past it - a point image on the line/area/plot charts, say, whose box
634
+ * is centered on a point at the top of the y domain and so hangs half of itself above the plot.
635
+ * Those charts already widen their clip-path to let such a point through; this is what stops
636
+ * the `<svg>` itself from cutting it off, the SVG being only the plot area plus the margins.
637
+ *
638
+ * "At least", not "add": the default margins, and any tick / label room already reserved in
639
+ * them, may well cover it already (`margin.left` is 40 by default), and adding on top of that
640
+ * would give up plot area for nothing. Vertical growth is taken out of the plot height the same
641
+ * way `reserveTickSizeMargins()`'s is, so the SVG's total height stays what the consumer
642
+ * configured; horizontally `initializeChartState()` picks the change up on its own. A side
643
+ * left `undefined` is untouched.
644
+ *
645
+ * Call after `initializeAxisState()` (which resets the margins) and before
646
+ * `initializeChartState()` (which measures the plot area against them).
647
+ */
648
+ reserveEdgeSpace(space: Partial<PcacChartMargin>): void;
581
649
  /**
582
650
  * Shows the tooltip for a hovered datum, through the chart's `pcacTooltip` template when one is
583
651
  * projected and the default key/value content otherwise. Every builder's hover handler should
@@ -693,10 +761,8 @@ declare class PcacBarHorizontalChartComponent {
693
761
  }
694
762
 
695
763
  declare class PcacBarVerticalChartConfig extends PcacAxisChartConfig {
696
- domainMax: number;
697
764
  isStacked: boolean;
698
765
  thresholds: PcacData[];
699
- tickFormat: PcacFormatEnum;
700
766
  spreadColorsPerGroup: boolean;
701
767
  colorOverride: PcacBarVerticalChartColorOverrideConfig;
702
768
  }
@@ -803,15 +869,18 @@ declare class PcacPointImageConfig {
803
869
  maxWidth: number;
804
870
  maxHeight: number;
805
871
  }
872
+ /**
873
+ * The axes' `format` and `domainMin`/`domainMax` (`PcacAxisConfig`) do more here than on the bar
874
+ * charts. `yAxis.domainMin`/`domainMax` are the y scale's domain (default 0..100). `xAxis.format`
875
+ * decides how each point's `key` becomes an x position: `Decimal` reads it as a number on a
876
+ * linear scale from `xAxis.domainMin` to `domainMax`, `DateTime` parses it with `new Date()` on
877
+ * a time scale between the two (both required), and every other format - including the default -
878
+ * places points by their index within their series, sizing the axis from the first series'
879
+ * length and ignoring the domain fields.
880
+ */
806
881
  declare class PcacLineAreaChartConfig extends PcacAxisChartConfig {
807
882
  enableEffects: boolean;
808
883
  enableZoom: boolean;
809
- yFormat: PcacFormatEnum;
810
- xFormat: PcacFormatEnum;
811
- yDomainMax: number | string;
812
- yDomainMin: number | string;
813
- xDomainMin: number | string;
814
- xDomainMax: number | string;
815
884
  /**
816
885
  * Hex color codes to override the default colors
817
886
  */
@@ -824,7 +893,42 @@ declare class PcacLineAreaChartConfig extends PcacAxisChartConfig {
824
893
  pointImage?: Partial<PcacPointImageConfig>;
825
894
  }
826
895
 
896
+ /**
897
+ * How the plot chart spreads out points that share a coordinate (see
898
+ * `PcacPlotChartConfig.pointFanOut`). Each group of coincident points is placed evenly around
899
+ * a ring centered on the shared coordinate, starting at 12 o'clock and going clockwise in data
900
+ * order (series order, then point order), so every point stays visible and hoverable.
901
+ */
902
+ declare class PcacPointFanOutConfig {
903
+ /**
904
+ * Ring radius in px, the same for every group. When not set, each group gets the smallest
905
+ * radius at which its neighbours sit `gap` px apart - so a pair barely moves while a group of
906
+ * five spreads as far as it has to.
907
+ */
908
+ radius?: number;
909
+ /**
910
+ * Space between neighbouring points on the ring, in px, when `radius` is not set. Measured
911
+ * between their image boxes (or hovered dots), not their centers.
912
+ */
913
+ gap: number;
914
+ /**
915
+ * Draw a dot at the shared coordinate - the value the group's points actually have - with a
916
+ * spoke out to each of them. Styled by the theme's `.fan-out-anchor` / `.fan-out-spoke` rules.
917
+ */
918
+ showAnchor: boolean;
919
+ }
827
920
  declare class PcacPlotChartConfig extends PcacLineAreaChartConfig {
921
+ /**
922
+ * Spread points that share a coordinate around it instead of drawing them on top of one
923
+ * another (where only the last series' point shows, and only it can be hovered). Off when not
924
+ * set; `{}` turns it on with every `PcacPointFanOutConfig` default. The fanned points keep
925
+ * their true value in the tooltip, and the hovered point's tooltip context lists the others at
926
+ * its coordinate in `coincident` (see `PcacTooltipContext`).
927
+ *
928
+ * Plot chart only: a line or area chart's points are joined in series order, so moving one
929
+ * would kink the line.
930
+ */
931
+ pointFanOut?: Partial<PcacPointFanOutConfig>;
828
932
  }
829
933
 
830
934
  declare class PcacPlotChart {
@@ -912,5 +1016,5 @@ declare class PcacPieChartComponent {
912
1016
  static ɵcmp: i0.ɵɵComponentDeclaration<PcacPieChartComponent, "pcac-pie-chart", never, { "config": { "alias": "config"; "required": true; "isSignal": true; }; }, { "sliceClicked": "sliceClicked"; }, ["tooltipTemplate"], never, true, never>;
913
1017
  }
914
1018
 
915
- export { BarHorizontalChartBuilder, BarVerticalChartBuilder, PCAC_AXIS_LABEL_SPACE, PCAC_AXIS_SUB_LABEL_SPACE, PcacAreaChart, PcacAreaChartConfig, PcacAxisBuilder, PcacAxisChartConfig, PcacAxisConfig, PcacAxisSubLabels, PcacBarHorizontalChartColorOverrideConfig, PcacBarHorizontalChartComponent, PcacBarHorizontalChartConfig, PcacBarVerticalChartColorOverrideConfig, PcacBarVerticalChartComponent, PcacBarVerticalChartConfig, PcacChart, PcacChartConfig, PcacChartResizeService, PcacColorService, PcacData, PcacFormatEnum, PcacGridBuilder, PcacLegend, PcacLegendConfig, PcacLegendConfigItem, PcacLineChart, PcacLineChartConfig, PcacPieChartComponent, PcacPieChartConfig, PcacPlotChart, PcacPlotChartConfig, PcacPointImageConfig, PcacTooltipBuilder, PcacTooltipDirective, PcacTransitionService, PieChartBuilder, axisLabelSpace, hasAxisSubLabels, resolveAxisConfig };
916
- export type { IPcacAxisBuilderConfig, IPcacGridBuilderConfig, PcacChartMargin, PcacResolvedAxisConfig, PcacTooltipContext, PcacTooltipOptions };
1019
+ export { BarHorizontalChartBuilder, BarVerticalChartBuilder, PCAC_AXIS_LABEL_SPACE, PCAC_AXIS_SUB_LABEL_SPACE, PcacAreaChart, PcacAreaChartConfig, PcacAxisBuilder, PcacAxisChartConfig, PcacAxisConfig, PcacAxisSubLabels, PcacBarHorizontalChartColorOverrideConfig, PcacBarHorizontalChartComponent, PcacBarHorizontalChartConfig, PcacBarVerticalChartColorOverrideConfig, PcacBarVerticalChartComponent, PcacBarVerticalChartConfig, PcacChart, PcacChartConfig, PcacChartResizeService, PcacColorService, PcacData, PcacFormatEnum, PcacGridBuilder, PcacLegend, PcacLegendConfig, PcacLegendConfigItem, PcacLineChart, PcacLineChartConfig, PcacPieChartComponent, PcacPieChartConfig, PcacPlotChart, PcacPlotChartConfig, PcacPointFanOutConfig, PcacPointImageConfig, PcacTooltipBuilder, PcacTooltipDirective, PcacTransitionService, PieChartBuilder, axisLabelSpace, hasAxisSubLabels, resolveAxisConfig };
1020
+ export type { IPcacAxisBuilderConfig, IPcacGridBuilderConfig, PcacChartMargin, PcacResolvedAxisConfig, PcacTooltipCoincident, PcacTooltipContext, PcacTooltipOptions };