@pioneer-code/pioneer-charts 22.2.0 → 22.2.1

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.1",
26
26
  "license": "MIT",
27
27
  "peerDependencies": {
28
28
  "@angular/common": "^22.1.0",
@@ -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;
@@ -499,11 +515,13 @@ declare class PcacChart {
499
515
  private lastContainerHeight;
500
516
  private lastHeightFull;
501
517
  /**
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.
518
+ * How much the vertical margins have grown this build beyond their defaults - for tick marks
519
+ * and axis labels (`initializeAxisState()`; negative when a short tick took some away) and for
520
+ * content that hangs past the plot's edge (`reserveEdgeSpace()`). `resolveHeight()` subtracts
521
+ * it from the plot height so the SVG's total height doesn't change with any of them. Reset
522
+ * alongside the margins.
505
523
  */
506
- private reservedTickHeight;
524
+ private reservedHeight;
507
525
  /**
508
526
  * Resolves the consumer's projected `<ng-template pcacTooltip>`, if any. Each chart component
509
527
  * points this at its own `contentChild(PcacTooltipDirective)` query. It's a getter rather than
@@ -545,11 +563,11 @@ declare class PcacChart {
545
563
  */
546
564
  initializeAxisState(config: PcacAxisChartConfig, defaultGrid: 'x' | 'y', hiddenAxisMargin?: number): void;
547
565
  /**
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).
566
+ * The `PcacAxisBuilder` config for this chart's current state - everything but the scales is
567
+ * already on the instance. Builders pass the result to `drawAxis()` (or `drawXAxis()` with a
568
+ * rescaled x, on zoom).
551
569
  */
552
- axisBuilderConfig<XDomain extends AxisDomain, YDomain extends AxisDomain>(xScale: AxisScale<XDomain>, yScale: AxisScale<YDomain>, xFormat?: PcacFormatEnum, yFormat?: PcacFormatEnum): IPcacAxisBuilderConfig<XDomain, YDomain>;
570
+ axisBuilderConfig<XDomain extends AxisDomain, YDomain extends AxisDomain>(xScale: AxisScale<XDomain>, yScale: AxisScale<YDomain>): IPcacAxisBuilderConfig<XDomain, YDomain>;
553
571
  /**
554
572
  * Draws whichever grids the resolved axes ask for: vertical lines from the x axis's ticks,
555
573
  * horizontal from the y's (`PcacAxisConfig.showGrid`). `which` restricts it to one axis - the
@@ -568,7 +586,7 @@ declare class PcacChart {
568
586
  * Horizontally that happens on its own: `initializeChartState()` derives `width` from the
569
587
  * container minus the margins. Vertically it doesn't - `config.height` is the plot area, and
570
588
  * 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
589
+ * delta is therefore also remembered in `reservedHeight` and taken back out of the plot
572
590
  * height by `resolveHeight()`, keeping the chart's total footprint where the consumer put it.
573
591
  *
574
592
  * Called by `initializeAxisState()` right after `resetMargin()`, for the axes that will be
@@ -578,6 +596,24 @@ declare class PcacChart {
578
596
  * @param yTickSize `tickSizeInner` for the left (y) axis, which lives in `margin.left`
579
597
  */
580
598
  reserveTickSizeMargins(xTickSize?: number, yTickSize?: number): void;
599
+ /**
600
+ * Makes sure each given margin is at least that big, for content drawn at the very edge of the
601
+ * plot area that reaches past it - a point image on the line/area/plot charts, say, whose box
602
+ * is centered on a point at the top of the y domain and so hangs half of itself above the plot.
603
+ * Those charts already widen their clip-path to let such a point through; this is what stops
604
+ * the `<svg>` itself from cutting it off, the SVG being only the plot area plus the margins.
605
+ *
606
+ * "At least", not "add": the default margins, and any tick / label room already reserved in
607
+ * them, may well cover it already (`margin.left` is 40 by default), and adding on top of that
608
+ * would give up plot area for nothing. Vertical growth is taken out of the plot height the same
609
+ * way `reserveTickSizeMargins()`'s is, so the SVG's total height stays what the consumer
610
+ * configured; horizontally `initializeChartState()` picks the change up on its own. A side
611
+ * left `undefined` is untouched.
612
+ *
613
+ * Call after `initializeAxisState()` (which resets the margins) and before
614
+ * `initializeChartState()` (which measures the plot area against them).
615
+ */
616
+ reserveEdgeSpace(space: Partial<PcacChartMargin>): void;
581
617
  /**
582
618
  * Shows the tooltip for a hovered datum, through the chart's `pcacTooltip` template when one is
583
619
  * projected and the default key/value content otherwise. Every builder's hover handler should
@@ -693,10 +729,8 @@ declare class PcacBarHorizontalChartComponent {
693
729
  }
694
730
 
695
731
  declare class PcacBarVerticalChartConfig extends PcacAxisChartConfig {
696
- domainMax: number;
697
732
  isStacked: boolean;
698
733
  thresholds: PcacData[];
699
- tickFormat: PcacFormatEnum;
700
734
  spreadColorsPerGroup: boolean;
701
735
  colorOverride: PcacBarVerticalChartColorOverrideConfig;
702
736
  }
@@ -803,15 +837,18 @@ declare class PcacPointImageConfig {
803
837
  maxWidth: number;
804
838
  maxHeight: number;
805
839
  }
840
+ /**
841
+ * The axes' `format` and `domainMin`/`domainMax` (`PcacAxisConfig`) do more here than on the bar
842
+ * charts. `yAxis.domainMin`/`domainMax` are the y scale's domain (default 0..100). `xAxis.format`
843
+ * decides how each point's `key` becomes an x position: `Decimal` reads it as a number on a
844
+ * linear scale from `xAxis.domainMin` to `domainMax`, `DateTime` parses it with `new Date()` on
845
+ * a time scale between the two (both required), and every other format - including the default -
846
+ * places points by their index within their series, sizing the axis from the first series'
847
+ * length and ignoring the domain fields.
848
+ */
806
849
  declare class PcacLineAreaChartConfig extends PcacAxisChartConfig {
807
850
  enableEffects: boolean;
808
851
  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
852
  /**
816
853
  * Hex color codes to override the default colors
817
854
  */