feat(schedule-details): add pure metrics chart scales (SLICE-9.1 / PR09b)

Introduce unit-tested time-to-pixel scale helpers with future gutter padding right of now, ready for axes and series in PR09c–d.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Assem-Uber

src/views/schedule-page/schedule-detail-metrics-chart/__tests__/schedule-detail-metrics-chart-scales.node.ts

@@ -0,0 +1,171 @@
+import {
+  CHART_DEFAULT_PAST_WINDOW_MS,
+  CHART_FUTURE_GUTTER_MS,
+  CHART_MIN_DOMAIN_SPAN_MS,
+  CHART_SIDE_PADDING_PX,
+} from '../schedule-detail-metrics-chart.constants';
+import {
+  createMetricsChartXScale,
+  pixelToTimeMs,
+  resolveMetricsChartPixelRange,
+  resolveMetricsChartTimeDomain,
+  timeMsToPixel,
+} from '../schedule-detail-metrics-chart-scales';
+
+const mockNowMs = new Date('2024-06-15T12:00:00Z').getTime();
+
+describe(resolveMetricsChartTimeDomain.name, () => {
+  it('returns a default past window ending with future gutter when timestamps are empty', () => {
+    const domain = resolveMetricsChartTimeDomain({
+      timestampsMs: [],
+      nowMs: mockNowMs,
+    });
+
+    expect(domain).toEqual({
+      minMs: mockNowMs - CHART_DEFAULT_PAST_WINDOW_MS,
+      maxMs: mockNowMs + CHART_FUTURE_GUTTER_MS,
+    });
+  });
+
+  it('extends the domain max using next execution plus future gutter', () => {
+    const nextExecutionMs = mockNowMs + 15 * 60_000;
+
+    const domain = resolveMetricsChartTimeDomain({
+      timestampsMs: [mockNowMs - 2 * 60 * 60_000],
+      nowMs: mockNowMs,
+      nextExecutionMs,
+    });
+
+    expect(domain).toEqual({
+      minMs: mockNowMs - 2 * 60 * 60_000,
+      maxMs: nextExecutionMs + CHART_FUTURE_GUTTER_MS,
+    });
+  });
+
+  it('pads the domain right of now even when all timestamps are in the past', () => {
+    const domain = resolveMetricsChartTimeDomain({
+      timestampsMs: [mockNowMs - 3 * 60 * 60_000, mockNowMs - 60_000],
+      nowMs: mockNowMs,
+    });
+
+    expect(domain?.maxMs).toBe(mockNowMs + CHART_FUTURE_GUTTER_MS);
+    expect(domain?.minMs).toBe(mockNowMs - 3 * 60 * 60_000);
+  });
+
+  it('anchors a single timestamp at now and pads the future gutter to the right', () => {
+    const domain = resolveMetricsChartTimeDomain({
+      timestampsMs: [mockNowMs],
+      nowMs: mockNowMs,
+    });
+
+    expect(domain).toEqual({
+      minMs: mockNowMs,
+      maxMs: mockNowMs + CHART_FUTURE_GUTTER_MS,
+    });
+  });
+
+  it('expands a collapsed domain to the minimum span when span would otherwise be zero', () => {
+    const pointMs = mockNowMs - 60_000;
+
+    const domain = resolveMetricsChartTimeDomain({
+      timestampsMs: [pointMs, pointMs],
+      nowMs: pointMs,
+      nextExecutionMs: pointMs,
+    });
+
+    expect(domain?.maxMs! - domain?.minMs!).toBeGreaterThanOrEqual(
+      CHART_MIN_DOMAIN_SPAN_MS
+    );
+  });
+
+  it('returns null when nowMs is not finite', () => {
+    expect(
+      resolveMetricsChartTimeDomain({
+        timestampsMs: [mockNowMs],
+        nowMs: Number.NaN,
+      })
+    ).toBeNull();
+  });
+
+  it('ignores non-finite timestamps', () => {
+    const domain = resolveMetricsChartTimeDomain({
+      timestampsMs: [Number.NaN, mockNowMs - 60_000],
+      nowMs: mockNowMs,
+    });
+
+    expect(domain?.minMs).toBe(mockNowMs - 60_000);
+    expect(domain?.maxMs).toBe(mockNowMs + CHART_FUTURE_GUTTER_MS);
+  });
+});
+
+describe(resolveMetricsChartPixelRange.name, () => {
+  it('maps chart width to a padded drawable pixel range', () => {
+    expect(
+      resolveMetricsChartPixelRange({
+        widthPx: 800,
+        sidePaddingPx: CHART_SIDE_PADDING_PX,
+      })
+    ).toEqual({
+      startPx: CHART_SIDE_PADDING_PX,
+      endPx: 800 - CHART_SIDE_PADDING_PX,
+    });
+  });
+
+  it('returns null when width is zero or negative', () => {
+    expect(resolveMetricsChartPixelRange({ widthPx: 0 })).toBeNull();
+    expect(resolveMetricsChartPixelRange({ widthPx: -10 })).toBeNull();
+  });
+
+  it('returns null when side padding consumes the full width', () => {
+    expect(
+      resolveMetricsChartPixelRange({
+        widthPx: CHART_SIDE_PADDING_PX * 2,
+        sidePaddingPx: CHART_SIDE_PADDING_PX,
+      })
+    ).toBeNull();
+  });
+});
+
+describe('metrics chart x scale', () => {
+  const domain = {
+    minMs: mockNowMs - 60 * 60_000,
+    maxMs: mockNowMs + CHART_FUTURE_GUTTER_MS,
+  };
+  const range = {
+    startPx: CHART_SIDE_PADDING_PX,
+    endPx: 776,
+  };
+
+  it('maps domain endpoints to pixel range', () => {
+    const scale = createMetricsChartXScale({ domain, range });
+
+    expect(scale).not.toBeNull();
+    expect(timeMsToPixel(domain.minMs, scale!)).toBe(range.startPx);
+    expect(timeMsToPixel(domain.maxMs, scale!)).toBe(range.endPx);
+    expect(timeMsToPixel(mockNowMs, scale!)).toBeGreaterThan(range.startPx);
+    expect(timeMsToPixel(mockNowMs, scale!)).toBeLessThan(range.endPx);
+  });
+
+  it('inverts pixel positions back to timestamps', () => {
+    const scale = createMetricsChartXScale({ domain, range })!;
+
+    expect(pixelToTimeMs(range.startPx, scale)).toBe(domain.minMs);
+    expect(pixelToTimeMs(range.endPx, scale)).toBe(domain.maxMs);
+  });
+
+  it('returns null for invalid domain or range', () => {
+    expect(
+      createMetricsChartXScale({
+        domain: { minMs: mockNowMs, maxMs: mockNowMs },
+        range,
+      })
+    ).toBeNull();
+
+    expect(
+      createMetricsChartXScale({
+        domain,
+        range: { startPx: 100, endPx: 100 },
+      })
+    ).toBeNull();
+  });
+});

src/views/schedule-page/schedule-detail-metrics-chart/schedule-detail-metrics-chart-scales.ts

@@ -0,0 +1,128 @@
+import { scaleLinear } from '@visx/scale';
+import { type ScaleLinear } from 'd3-scale';
+
+import {
+  CHART_DEFAULT_PAST_WINDOW_MS,
+  CHART_FUTURE_GUTTER_MS,
+  CHART_MIN_DOMAIN_SPAN_MS,
+  CHART_SIDE_PADDING_PX,
+} from './schedule-detail-metrics-chart.constants';
+import {
+  type CreateMetricsChartXScaleParams,
+  type MetricsChartPixelRange,
+  type MetricsChartTimeDomain,
+  type ResolveMetricsChartPixelRangeParams,
+  type ResolveMetricsChartTimeDomainParams,
+} from './schedule-detail-metrics-chart.types';
+
+type MetricsChartXScale = ScaleLinear<number, number, never>;
+
+export function resolveMetricsChartTimeDomain({
+  timestampsMs,
+  nowMs,
+  nextExecutionMs,
+}: ResolveMetricsChartTimeDomainParams): MetricsChartTimeDomain | null {
+  if (!Number.isFinite(nowMs)) {
+    return null;
+  }
+
+  const validTimestampsMs = timestampsMs.filter(Number.isFinite);
+
+  if (validTimestampsMs.length === 0 && nextExecutionMs == null) {
+    return {
+      minMs: nowMs - CHART_DEFAULT_PAST_WINDOW_MS,
+      maxMs: nowMs + CHART_FUTURE_GUTTER_MS,
+    };
+  }
+
+  const dataMinMs =
+    validTimestampsMs.length > 0
+      ? Math.min(...validTimestampsMs)
+      : nowMs;
+  const dataMaxMs =
+    validTimestampsMs.length > 0
+      ? Math.max(...validTimestampsMs)
+      : nowMs;
+
+  let minMs = Math.min(dataMinMs, nowMs);
+  let maxMs = Math.max(dataMaxMs, nowMs, nowMs + CHART_FUTURE_GUTTER_MS);
+
+  if (
+    nextExecutionMs != null &&
+    Number.isFinite(nextExecutionMs) &&
+    nextExecutionMs > nowMs
+  ) {
+    maxMs = Math.max(maxMs, nextExecutionMs + CHART_FUTURE_GUTTER_MS);
+  }
+
+  if (maxMs <= minMs) {
+    maxMs = minMs + CHART_MIN_DOMAIN_SPAN_MS;
+  } else if (maxMs - minMs < CHART_MIN_DOMAIN_SPAN_MS) {
+    const centerMs = (minMs + maxMs) / 2;
+    minMs = centerMs - CHART_MIN_DOMAIN_SPAN_MS / 2;
+    maxMs = centerMs + CHART_MIN_DOMAIN_SPAN_MS / 2;
+  }
+
+  return { minMs, maxMs };
+}
+
+export function resolveMetricsChartPixelRange({
+  widthPx,
+  sidePaddingPx = CHART_SIDE_PADDING_PX,
+}: ResolveMetricsChartPixelRangeParams): MetricsChartPixelRange | null {
+  if (!Number.isFinite(widthPx) || widthPx <= 0) {
+    return null;
+  }
+
+  const drawableWidthPx = widthPx - sidePaddingPx * 2;
+
+  if (drawableWidthPx <= 0) {
+    return null;
+  }
+
+  return {
+    startPx: sidePaddingPx,
+    endPx: sidePaddingPx + drawableWidthPx,
+  };
+}
+
+export function createMetricsChartXScale({
+  domain,
+  range,
+}: CreateMetricsChartXScaleParams): MetricsChartXScale | null {
+  if (
+    !Number.isFinite(domain.minMs) ||
+    !Number.isFinite(domain.maxMs) ||
+    domain.maxMs <= domain.minMs
+  ) {
+    return null;
+  }
+
+  if (
+    !Number.isFinite(range.startPx) ||
+    !Number.isFinite(range.endPx) ||
+    range.endPx <= range.startPx
+  ) {
+    return null;
+  }
+
+  return scaleLinear<number>({
+    domain: [domain.minMs, domain.maxMs],
+    range: [range.startPx, range.endPx],
+    clamp: true,
+  });
+}
+
+export function timeMsToPixel(
+  timeMs: number,
+  scale: MetricsChartXScale
+): number {
+  return scale(timeMs);
+}
+
+export function pixelToTimeMs(
+  pixel: number,
+  scale: MetricsChartXScale
+): number {
+  return scale.invert(pixel);
+}

src/views/schedule-page/schedule-detail-metrics-chart/schedule-detail-metrics-chart.constants.ts

@@ -12,3 +12,15 @@ export const CHART_EMPTY_STATE_MESSAGE = 'No chart data available yet';
 export const CHART_REGION_ARIA_LABEL = 'Schedule metrics chart';
 
 export const CHART_TOOLBAR_ARIA_LABEL = 'Chart controls';
+
+/** Minimum time span when domain collapses to a single timestamp (ms). */
+export const CHART_MIN_DOMAIN_SPAN_MS = 5 * 60_000;
+
+/** Default past window when no run timestamps are available (ms). */
+export const CHART_DEFAULT_PAST_WINDOW_MS = 6 * 60 * 60_000;
+
+/** Padding to the right of `now` reserved for upcoming expected executions (ms). */
+export const CHART_FUTURE_GUTTER_MS = 30 * 60_000;
+
+/** Horizontal inset applied to the chart drawable area (px). */
+export const CHART_SIDE_PADDING_PX = 24;

src/views/schedule-page/schedule-detail-metrics-chart/schedule-detail-metrics-chart.types.ts

@@ -3,3 +3,29 @@ import { type SchedulePageTabsParams } from '@/views/schedule-page/schedule-page
 export type Props = {
   params: SchedulePageTabsParams;
 };
+
+export type MetricsChartTimeDomain = {
+  minMs: number;
+  maxMs: number;
+};
+
+export type MetricsChartPixelRange = {
+  startPx: number;
+  endPx: number;
+};
+
+export type ResolveMetricsChartTimeDomainParams = {
+  timestampsMs: number[];
+  nowMs: number;
+  nextExecutionMs?: number | null;
+};
+
+export type ResolveMetricsChartPixelRangeParams = {
+  widthPx: number;
+  sidePaddingPx?: number;
+};
+
+export type CreateMetricsChartXScaleParams = {
+  domain: MetricsChartTimeDomain;
+  range: MetricsChartPixelRange;
+};