Stop a percentage Y axis expanding past 100

A percentage has a real ceiling the way zero is a real floor, but the gap that
keeps series off the plot edges did not know that: a battery reading 20-100%
rounded out to an axis labelled up to 120%, and one sitting flat at 100% — a
device left on the charger — reached 160%.

Recognise the unit at the two line-chart call sites and hold the axis at 100,
mirroring the existing zero clamp. Only while the data stays under it, since
power factor is also reported in % and is signed.

Author: MindFreeze

src/components/chart/state-history-chart-line.ts

@@ -328,6 +328,7 @@ export class StateHistoryChartLine extends LitElement {
           ...createYAxisPrecisionBounds({
             min: this._clampYAxis(minYAxis),
             max: this._clampYAxis(maxYAxis),
+            unit: this.unit,
             onFractionDigits: (digits) => {
               if (digits !== this._yAxisFractionDigits) {
                 this._yAxisFractionDigits = digits;

src/components/chart/statistics-chart.ts

@@ -446,6 +446,7 @@ export class StatisticsChart extends LitElement {
         ...createYAxisPrecisionBounds({
           min: this._clampYAxis(minYAxis),
           max: this._clampYAxis(maxYAxis),
+          unit: this.unit,
           // Bar charts stay anchored at 0, so precision must reflect the
           // 0-based range that is actually rendered.
           includeZero: !yAxisScale,

src/components/chart/y-axis-fraction-digits.ts

@@ -18,6 +18,11 @@ const SPLIT_NUMBER = 5;
 // headroom out to a full tick, and leaves the rest where they are.
 const GAP_FRACTION_OF_SPAN = 0.02;
 
+// A percentage has a real ceiling the way zero is a real floor, so the gap must
+// not push the axis past it. Not every `%` sensor is bounded — power factor is
+// signed and can read over 100 — so this only applies while the data stays under.
+const PERCENT_MAX = 100;
+
 // Derive the number of decimal digits to use for Y-axis labels from the
 // observed data range, by asking ECharts for the same tick interval it will
 // render. This matches the precision it actually draws, so labels are neither
@@ -81,14 +86,18 @@ export function createYAxisPrecisionBounds(options: {
   // Such an axis also gets no gap: pushing it below zero would defeat the zero
   // anchoring and leave the bars floating above the axis.
   includeZero?: boolean;
+  // Used to recognise a bounded quantity, so the gap cannot widen the axis past
+  // a limit the data itself never crosses.
+  unit?: string;
   onFractionDigits: (digits: number) => void;
 }): {
   min: (values: YAxisExtentValues) => number | undefined;
   max: (values: YAxisExtentValues) => number | undefined;
   boundaryGap: [number, number];
   splitNumber: number;
 } {
-  const { min, max, includeZero, onFractionDigits } = options;
+  const { min, max, includeZero, unit, onFractionDigits } = options;
+  const naturalMax = unit === "%" ? PERCENT_MAX : undefined;
 
   const resolveBounds = (values: YAxisExtentValues) => {
     const resolvedMin = resolveYAxisBound(min, values);
@@ -105,18 +114,36 @@ export function createYAxisPrecisionBounds(options: {
         resolvedMin !== undefined,
         resolvedMax !== undefined,
       ]);
+      // The expansion is a fraction of the magnitude, so a constant series near
+      // the ceiling would otherwise overshoot it too.
+      const flatMax =
+        naturalMax !== undefined && values.max <= naturalMax
+          ? Math.min(flat.max, naturalMax)
+          : flat.max;
       return {
         min: resolvedMin ?? flat.min,
-        max: resolvedMax ?? flat.max,
+        max: resolvedMax ?? flatMax,
         gap: 0,
       };
     }
     const gap = (values.max - values.min) * GAP_FRACTION_OF_SPAN;
-    // Never let the gap carry a single-signed series across zero.
+    // Never let the gap carry a series past a boundary it does not itself cross.
+    const floor = values.min >= 0 ? 0 : undefined;
+    const ceiling =
+      naturalMax !== undefined && values.max <= naturalMax
+        ? naturalMax
+        : values.max <= 0
+          ? 0
+          : undefined;
     return {
-      min: resolvedMin ?? (values.min >= 0 && values.min < gap ? 0 : undefined),
+      min:
+        resolvedMin ??
+        (floor !== undefined && values.min - floor < gap ? floor : undefined),
       max:
-        resolvedMax ?? (values.max <= 0 && -values.max < gap ? 0 : undefined),
+        resolvedMax ??
+        (ceiling !== undefined && ceiling - values.max < gap
+          ? ceiling
+          : undefined),
       gap,
     };
   };

test/components/chart/y-axis-boundary-gap.test.ts

@@ -42,10 +42,11 @@ const renderExtent = (
   return extent;
 };
 
-const withGap = (includeZero = false) => ({
+const withGap = (includeZero = false, unit?: string) => ({
   scale: !includeZero,
   ...createYAxisPrecisionBounds({
     includeZero,
+    unit,
     onFractionDigits: () => undefined,
   }),
 });
@@ -88,6 +89,12 @@ describe("Y-axis tick nudge", () => {
     );
   });
 
+  it("does not round a percentage axis past 100", () => {
+    const battery = [20, 100, 60, 20, 80];
+    expect(renderExtent(battery, withGap())).toEqual([0, 120]);
+    expect(renderExtent(battery, withGap(false, "%"))).toEqual([0, 100]);
+  });
+
   it("re-anchors at zero when a chart switches to a zero-anchored type", () => {
     // setOption merges the Y axis, so a gap that is only emitted conditionally
     // survives the switch and leaves the bars floating.

test/components/chart/y-axis-fraction-digits.test.ts

@@ -186,6 +186,42 @@ describe("createYAxisPrecisionBounds", () => {
     expect(max({ min: 0, max: 0 })).toBe(1);
   });
 
+  it("stops a percentage axis at 100 the way it stops at zero", () => {
+    const { max } = makeBounds({ unit: "%" });
+
+    // A battery that reaches full would otherwise round out to an axis
+    // labelled up to 120%.
+    expect(max({ min: 20, max: 100 })).toBe(100);
+    expect(max({ min: 20, max: 99 })).toBe(100);
+
+    // Well clear of the ceiling, so it still gets its gap.
+    expect(max({ min: 40, max: 60 })).toBeUndefined();
+
+    // Not every % sensor is bounded: power factor is signed and can read over
+    // 100, and a series already past the ceiling must be left alone.
+    expect(max({ min: -80, max: 140 })).toBeUndefined();
+  });
+
+  it("holds a constant percentage under the ceiling too", () => {
+    const { max } = makeBounds({ unit: "%" });
+
+    // A device left on the charger reads a flat 100%, and the expansion a flat
+    // series gets is a fraction of its magnitude, so it overshoots on its own.
+    expect(max({ min: 100, max: 100 })).toBe(100);
+    expect(max({ min: 80, max: 80 })).toBe(100);
+
+    // Far enough below that the expansion never reaches the ceiling.
+    expect(max({ min: 54, max: 54 })).toBe(90);
+  });
+
+  it("only treats a percentage as bounded", () => {
+    // The same extent without the unit is widened as usual.
+    expect(makeBounds().max({ min: 20, max: 100 })).toBeUndefined();
+    expect(
+      makeBounds({ unit: "W" }).max({ min: 20, max: 100 })
+    ).toBeUndefined();
+  });
+
   it("never widens a zero-anchored axis", () => {
     const { min, max, boundaryGap } = makeBounds({ includeZero: true });