@torpor/ui 1.2.3 → 1.3.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.
@@ -1,8 +1,6 @@
1
1
  import { $watch } from "@torpor/view";
2
2
  import type DataSeries from "../Charts/DataSeries";
3
3
  import {
4
- calculateChartBottom,
5
- calculateChartLeft,
6
4
  calculateItemWidth,
7
5
  calculateMaxValue,
8
6
  calculateStepLabels,
@@ -10,6 +8,9 @@ import {
10
8
  calculateValueHeight,
11
9
  } from "./chartUtils";
12
10
 
11
+ /** The sides of a chart that space can be reserved on */
12
+ export type ChartSide = "top" | "right" | "bottom" | "left";
13
+
13
14
  export interface ChartLayoutOptions {
14
15
  /** The named series to lay out */
15
16
  series: () => DataSeries[];
@@ -17,10 +18,6 @@ export interface ChartLayoutOptions {
17
18
  height?: () => number | undefined;
18
19
  /** Fixed width, if any (default 400 or the container's client width) */
19
20
  width?: () => number | undefined;
20
- /** Label under the x axis */
21
- xLabel?: () => string | undefined;
22
- /** Label beside the y axis */
23
- yLabel?: () => string | undefined;
24
21
  /** The value at the top of the chart, instead of the series' maximum */
25
22
  maxValue?: () => number | undefined;
26
23
  /** The number of steps between 0 and the maximum value (default 2) */
@@ -32,20 +29,33 @@ export interface ChartLayoutOptions {
32
29
  }
33
30
 
34
31
  /**
35
- * The shared layout scaffold behind the cartesian charts (Bar, Column,
36
- * Line): measures the chart's text so labels can be sized, and calculates
37
- * the plot geometry -- maximum value, step sizes, slot widths and the
38
- * left/bottom margins -- reactively from the series and axis props.
32
+ * A claim on space along one side of the chart, made by an axis, legend or
33
+ * other furniture layer via `reserve`.
34
+ */
35
+ interface SpaceClaim {
36
+ side: ChartSide;
37
+ size: number;
38
+ }
39
+
40
+ /**
41
+ * The shared layout scaffold behind the layered charts: measures the chart's
42
+ * text so labels can be sized, and calculates the scales and the plot
43
+ * geometry reactively from the series and the space reserved by layers.
44
+ *
45
+ * Furniture layers (axes, legends) claim the space they need with `reserve`;
46
+ * the plot rect is whatever is left over, and mark layers draw only into
47
+ * that, overlapping each other freely. Aggregated marks (stacks) raise the
48
+ * domain with `announceMax`.
39
49
  *
40
- * Charts render only their own marks; call `measure` from `$onmount` with the
41
- * hidden `<text>` element they render for that purpose.
50
+ * Charts render only their own marks; call `measureChartText` from
51
+ * `$onmount` with the hidden `<text>` element they render for that purpose.
42
52
  *
43
53
  * ```
44
54
  * let $layout = createChartLayout({
45
55
  * series: () => $props.series,
46
56
  * getContainer: () => container,
47
57
  * });
48
- * $onmount(() => setTimeout(() => measure($layout, measurer), 1));
58
+ * $onmount(() => setTimeout(() => measureChartText($layout, measurer), 1));
49
59
  * ```
50
60
  */
51
61
  export interface ChartLayout {
@@ -57,20 +67,44 @@ export interface ChartLayout {
57
67
  readonly labels: string[];
58
68
  readonly calculatedHeight: number;
59
69
  readonly calculatedWidth: number;
60
- /** The largest value across all series, unless overridden */
70
+ /** The largest value across all series and announced stacks, unless overridden */
61
71
  readonly maxValue: number;
62
72
  /** The size of one y axis step */
63
73
  readonly stepValue: number;
64
74
  /** The labels for each step, 0 through max */
65
75
  readonly stepLabels: number[];
66
- /** The width of one category slot */
76
+ /** The width of one category slot in the plot */
67
77
  readonly itemWidth: number;
68
78
  /** The pixel height of one unit of value */
69
79
  readonly valueHeight: number;
70
- /** The bottom edge of the plot area */
71
- readonly chartBottom: number;
80
+ /** The space reserved along the top edge (e.g. a legend) */
81
+ readonly reservedTop: number;
82
+ /** The space reserved along the right edge (e.g. a right y axis) */
83
+ readonly reservedRight: number;
84
+ /** The space reserved along the bottom edge (e.g. an x axis) */
85
+ readonly reservedBottom: number;
86
+ /** The space reserved along the left edge (e.g. a left y axis) */
87
+ readonly reservedLeft: number;
72
88
  /** The left edge of the plot area */
73
- readonly chartLeft: number;
89
+ readonly plotX: number;
90
+ /** The top edge of the plot area */
91
+ readonly plotY: number;
92
+ /** The width of the plot area */
93
+ readonly plotWidth: number;
94
+ /** The height of the plot area */
95
+ readonly plotHeight: number;
96
+ /**
97
+ * Claims space on a side of the plot, keyed by layer. Claims on the
98
+ * same side stack up; no-ops when the claim is unchanged.
99
+ */
100
+ reserve(id: string, side: ChartSide, size: number): void;
101
+ /** Gives back the space claimed by `reserve` */
102
+ release(id: string): void;
103
+ /**
104
+ * Announces the domain top that an aggregated mark layer (a stack)
105
+ * needs, keyed by layer. No-ops when the value is unchanged.
106
+ */
107
+ announceMax(id: string, value: number): void;
74
108
  setTextSize(width: number, height: number): void;
75
109
  }
76
110
 
@@ -83,6 +117,16 @@ export function createChartLayout(options: ChartLayoutOptions): ChartLayout {
83
117
  textWidth: 0,
84
118
  textHeight: 0,
85
119
 
120
+ // Space claimed by furniture layers (axes, legends), keyed by layer id
121
+ claims: {} as Record<string, SpaceClaim>,
122
+ // Domain tops announced by aggregated mark layers, keyed by layer id
123
+ maxClaims: {} as Record<string, number>,
124
+ // Bumped whenever the claims change: adding a key to a watched
125
+ // object doesn't notify on its own, so getters that iterate them
126
+ // read this to stay up to date
127
+ claimsVersion: 0,
128
+ maxVersion: 0,
129
+
86
130
  get labels() {
87
131
  return options.series().map((s) => s.name);
88
132
  },
@@ -93,7 +137,14 @@ export function createChartLayout(options: ChartLayoutOptions): ChartLayout {
93
137
  return options.width?.() || options.getContainer?.()?.clientWidth || defaultWidth;
94
138
  },
95
139
  get maxValue() {
96
- return options.maxValue?.() || calculateMaxValue(options.series());
140
+ void this.maxVersion;
141
+ return (
142
+ options.maxValue?.() ||
143
+ Math.max(
144
+ calculateMaxValue(options.series()),
145
+ ...Object.values(this.maxClaims as Record<string, number>),
146
+ )
147
+ );
97
148
  },
98
149
  get stepValue() {
99
150
  return options.stepValue?.() || calculateStepValue(this.maxValue, options.stepCount?.());
@@ -102,26 +153,63 @@ export function createChartLayout(options: ChartLayoutOptions): ChartLayout {
102
153
  return calculateStepLabels(getStepCount(), this.stepValue);
103
154
  },
104
155
  get itemWidth() {
105
- return calculateItemWidth(this.calculatedWidth, this.chartLeft, this.labels);
156
+ return calculateItemWidth(this.plotWidth, this.labels);
106
157
  },
107
158
  get valueHeight() {
108
- return calculateValueHeight(
109
- this.chartBottom,
110
- this.textHeight,
111
- this.stepValue,
112
- getStepCount(),
113
- );
159
+ return calculateValueHeight(this.plotHeight, this.textHeight, this.stepValue, getStepCount());
160
+ },
161
+
162
+ // The reserved strips, one per side: the largest claim on that side
163
+ get reservedTop() {
164
+ void this.claimsVersion;
165
+ return reservedSize(this.claims as Record<string, SpaceClaim>, "top");
114
166
  },
115
- get chartBottom() {
116
- return calculateChartBottom(options.xLabel?.() ?? "", this.calculatedHeight, this.textHeight);
167
+ get reservedRight() {
168
+ void this.claimsVersion;
169
+ return reservedSize(this.claims as Record<string, SpaceClaim>, "right");
117
170
  },
118
- get chartLeft() {
119
- return calculateChartLeft(
120
- this.stepLabels,
121
- options.yLabel?.() ?? "",
122
- this.textHeight,
123
- this.textWidth,
124
- );
171
+ get reservedBottom() {
172
+ void this.claimsVersion;
173
+ return reservedSize(this.claims as Record<string, SpaceClaim>, "bottom");
174
+ },
175
+ get reservedLeft() {
176
+ void this.claimsVersion;
177
+ return reservedSize(this.claims as Record<string, SpaceClaim>, "left");
178
+ },
179
+
180
+ // The plot rect: whatever is left over after reservations. Mark
181
+ // layers draw into this and overlap each other freely.
182
+ get plotX() {
183
+ return this.reservedLeft;
184
+ },
185
+ get plotY() {
186
+ return this.reservedTop;
187
+ },
188
+ get plotWidth() {
189
+ return Math.max(0, this.calculatedWidth - this.reservedLeft - this.reservedRight);
190
+ },
191
+ get plotHeight() {
192
+ return Math.max(0, this.calculatedHeight - this.reservedTop - this.reservedBottom);
193
+ },
194
+
195
+ reserve(id: string, side: ChartSide, size: number) {
196
+ const claims = this.claims as Record<string, SpaceClaim>;
197
+ const current = claims[id];
198
+ if (current && current.side === side && current.size === size) return;
199
+ claims[id] = { side, size };
200
+ this.claimsVersion++;
201
+ },
202
+ release(id: string) {
203
+ const claims = this.claims as Record<string, SpaceClaim>;
204
+ if (!claims[id]) return;
205
+ delete claims[id];
206
+ this.claimsVersion++;
207
+ },
208
+ announceMax(id: string, value: number) {
209
+ const claims = this.maxClaims as Record<string, number>;
210
+ if (claims[id] === value) return;
211
+ claims[id] = value;
212
+ this.maxVersion++;
125
213
  },
126
214
 
127
215
  setTextSize(width: number, height: number) {
@@ -131,6 +219,20 @@ export function createChartLayout(options: ChartLayoutOptions): ChartLayout {
131
219
  });
132
220
  }
133
221
 
222
+ /**
223
+ * The total space reserved on one side: claims on the same side stack up,
224
+ * so an x axis and a legend each keep their own band along the bottom.
225
+ */
226
+ function reservedSize(claims: Record<string, SpaceClaim>, side: ChartSide): number {
227
+ let total = 0;
228
+ for (const claim of Object.values(claims)) {
229
+ if (claim.side === side) {
230
+ total += claim.size;
231
+ }
232
+ }
233
+ return total;
234
+ }
235
+
134
236
  /**
135
237
  * Reads the size of a hidden measurer `<text>` element into the layout
136
238
  * state and removes it. Call once the element is in the document (from
@@ -38,17 +38,62 @@ export function calculateStepLabels(stepCount: number, stepValue: number): numbe
38
38
  return newStepLabels;
39
39
  }
40
40
 
41
- export function calculateItemWidth(width: number, chartLeft: number, labels: string[]): number {
42
- return (width - chartLeft) / labels.length;
41
+ export function calculateItemWidth(plotWidth: number, labels: string[]): number {
42
+ return plotWidth / labels.length;
43
43
  }
44
44
 
45
45
  export function calculateValueHeight(
46
- chartBottom: number,
46
+ plotHeight: number,
47
47
  textHeight: number,
48
48
  stepValue: number,
49
49
  stepCount: number,
50
50
  ): number {
51
- return (chartBottom - textHeight) / (stepValue * stepCount);
51
+ // A little headroom above the tallest mark
52
+ return (plotHeight - textHeight) / (stepValue * stepCount);
53
+ }
54
+
55
+ /**
56
+ * The width needed by a row of numeric tick labels, approximated from the
57
+ * measured width of a "0" character.
58
+ */
59
+ export function calculateTickLabelWidth(stepLabels: number[], textWidth: number): number {
60
+ const maxLabelLength = stepLabels.reduce((a, b) => Math.max(a, b.toString().length), 0);
61
+ return maxLabelLength * textWidth;
62
+ }
63
+
64
+ /**
65
+ * The domain top needed by marks that stack the series on top of each
66
+ * other (stacked areas, stacked lines): the largest sum across all series
67
+ * at one point.
68
+ */
69
+ export function calculateCrossStackMax(series: DataSeries[]): number {
70
+ const count = Math.max(0, ...series.map((s) => s.data.length));
71
+ let max = 0;
72
+ for (let j = 0; j < count; j++) {
73
+ let total = 0;
74
+ for (const s of series) {
75
+ total += s.data[j] ?? 0;
76
+ }
77
+ if (total > max) {
78
+ max = total;
79
+ }
80
+ }
81
+ return max;
82
+ }
83
+
84
+ /**
85
+ * The domain top needed by stacked marks (stacked columns, stacked bars):
86
+ * the largest sum of the values in one slot across all series.
87
+ */
88
+ export function calculateStackMax(series: DataSeries[]): number {
89
+ let max = 0;
90
+ for (const s of series) {
91
+ const total = s.data.reduce((a, b) => a + b, 0);
92
+ if (total > max) {
93
+ max = total;
94
+ }
95
+ }
96
+ return max;
52
97
  }
53
98
 
54
99
  export function calculateChartBottom(xLabel: string, height: number, textHeight: number): number {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@torpor/ui",
3
- "version": "1.2.3",
3
+ "version": "1.3.1",
4
4
  "description": "Accessible, unstyled components for use in your Torpor front-end",
5
5
  "type": "module",
6
6
  "torpor": true,
@@ -181,15 +181,15 @@
181
181
  "author": "",
182
182
  "license": "ISC",
183
183
  "dependencies": {
184
- "@torpor/unplugin": "^1.2.5",
185
- "@torpor/view": "^1.2.2"
184
+ "@torpor/unplugin": "^1.2.7",
185
+ "@torpor/view": "^1.2.4"
186
186
  },
187
187
  "devDependencies": {
188
188
  "@testing-library/dom": "^10.4.2",
189
189
  "@testing-library/jest-dom": "^7.0.1",
190
190
  "@testing-library/user-event": "^14.6.8",
191
- "@torpor/check": "^1.0.10",
192
- "@torpor/prettier": "^1.0.10",
191
+ "@torpor/check": "^1.0.12",
192
+ "@torpor/prettier": "^1.0.12",
193
193
  "@types/jsdom": "^30.0.0",
194
194
  "@types/node": "^26.6.5",
195
195
  "@typescript/native-preview": "7.0.0-dev.20260707.2",