@oneuptime/common 14.0.8 → 14.0.10

package/UI/Components/Charts/Utils/useHistogramRangeSelection.ts

@@ -1,18 +1,44 @@
-import React, { useCallback, useEffect, useRef, useState } from "react";
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import {
   HistogramSelectionWindow,
   getHistogramSelectionWindow,
 } from "./HistogramSelection";
-import { DOUBLE_CLICK_DISAMBIGUATION_MS } from "../ChartLibrary/Utils/DoubleClick";
+import {
+  ChartPointerEvent,
+  DOUBLE_CLICK_DISAMBIGUATION_MS,
+  DoubleClickReset,
+  useDoubleClickReset,
+} from "../ChartLibrary/Utils/DoubleClick";
+import {
+  CHART_PRESS_STILLNESS_PX,
+  RANGE_SELECTION_THROTTLED_EVENTS,
+} from "../ChartLibrary/Utils/UseChartRangeSelection";
+import OneUptimeDate from "../../../../Types/Date";
 
 /*
  * The part of recharts' chart state the handlers read. `activeLabel` is the
  * category under the pointer: the bucket start of the hovered bar.
+ * `activeTooltipIndex` is that category's place on the axis, which recharts
+ * works out again only when the pointer moves: bars landing under a still
+ * pointer keep the index and change the label.
  */
 export interface HistogramPointerState {
   activeLabel?: string | number | undefined;
+  activeTooltipIndex?: string | number | null | undefined;
 }
 
+/*
+ * How far the pointer may wander from where it was pressed and still be a
+ * pointer that has not moved - the line, area and bar charts' own measure.
+ */
+export const HISTOGRAM_PRESS_STILLNESS_PX: number = CHART_PRESS_STILLNESS_PX;
+
 export interface HistogramRangeSelectionOptions {
   onTimeRangeSelect?: ((startTime: Date, endTime: Date) => void) | undefined;
   onZoomOut?: (() => void) | undefined;
@@ -24,19 +50,73 @@ export interface HistogramRangeSelectionOptions {
 }
 
 export interface HistogramRangeSelectionState {
-  /** Bucket labels the selection band spans, or null while there is none. */
+  /*
+   * Labels of the first and last bar (in time order) the selection band
+   * spans, or null while there is none.
+   */
   selectionStart: string | null;
   selectionEnd: string | null;
-  /** True between the press and the release of a selection. */
+  /*
+   * True while a selection drags across bars - from the move that leaves
+   * the pressed bar to the release. A press that stays put is a click.
+   */
   isDragging: boolean;
   /** Whether a click on a single bar zooms into it. */
   canClickToZoom: boolean;
-  onMouseDown: (state?: HistogramPointerState | null) => void;
-  onMouseMove: (state?: HistogramPointerState | null) => void;
-  onMouseUp: (state?: HistogramPointerState | null) => void;
+  /*
+   * Spread onto the host's recharts chart root. recharts works out the bar
+   * under the pointer a frame after each mousemove by default, but hands
+   * mousedown and mouseup over at once, with the bar it last worked out -
+   * so a quick drag started a bar early or lost its last bars; a
+   * selectable histogram takes mousemove unthrottled (see
+   * RANGE_SELECTION_THROTTLED_EVENTS). Empty when nothing can be selected,
+   * which leaves recharts' default alone.
+   */
+  chartRootProps: HistogramChartRootProps;
+  /*
+   * The chart root's mouse handlers. recharts hands them its state and the
+   * React event; the event is optional so a caller without one still gets
+   * the label-only behaviour.
+   */
+  onMouseDown: (
+    state?: HistogramPointerState | null,
+    event?: ChartPointerEvent | null,
+  ) => void;
+  onMouseMove: (
+    state?: HistogramPointerState | null,
+    event?: ChartPointerEvent | null,
+  ) => void;
+  onMouseUp: (
+    state?: HistogramPointerState | null,
+    event?: ChartPointerEvent | null,
+  ) => void;
   onDoubleClick: () => void;
+  /*
+   * Spread onto a box that stands in for the chart - a loader while a
+   * window loads, an empty box when it holds nothing - so that it takes
+   * the double-click as the chart does: the second press as well as the
+   * dblclick. Right after a zoom the chart replaces its loader at any
+   * moment, a double-click in progress included, and the browser's
+   * dblclick does not survive that (see useDoubleClickReset).
+   */
+  placeholderProps: HistogramPlaceholderProps;
 }
 
+export interface HistogramChartRootProps {
+  throttledEvents?: ReadonlyArray<keyof GlobalEventHandlersEventMap>;
+}
+
+export interface HistogramPlaceholderProps {
+  onMouseDown: (event: React.MouseEvent<HTMLElement>) => void;
+  onDoubleClick: () => void;
+}
+
+const SELECTABLE_CHART_ROOT_PROPS: HistogramChartRootProps = {
+  throttledEvents: RANGE_SELECTION_THROTTLED_EVENTS,
+};
+
+const INERT_CHART_ROOT_PROPS: HistogramChartRootProps = {};
+
 export type UseHistogramRangeSelectionFunction = (
   options: HistogramRangeSelectionOptions,
 ) => HistogramRangeSelectionState;
@@ -51,6 +131,43 @@ function toLabel(state?: HistogramPointerState | null): string | null {
   return String(label);
 }
 
+// Where the pointer was, and the bar recharts named under it.
+interface PointerReport {
+  clientX: number | null;
+  label: string | null;
+}
+
+function toAxisIndex(state?: HistogramPointerState | null): string | null {
+  const index: string | number | null | undefined = state?.activeTooltipIndex;
+
+  if (index === undefined || index === null || index === "") {
+    return null;
+  }
+
+  return String(index);
+}
+
+/*
+ * Two bars' labels in time order. recharts draws a band's x1 from the left
+ * edge of its bar and x2 to the right edge of its own, so a band in drag
+ * order shaded neither end bar of a right-to-left drag (and nothing at all
+ * across two neighbours). Labels that are not dates keep their order.
+ */
+function inTimeOrder(first: string, second: string): [string, string] {
+  const firstMs: number = OneUptimeDate.fromString(first).getTime();
+  const secondMs: number = OneUptimeDate.fromString(second).getTime();
+
+  if (
+    Number.isFinite(firstMs) &&
+    Number.isFinite(secondMs) &&
+    secondMs < firstMs
+  ) {
+    return [second, first];
+  }
+
+  return [first, second];
+}
+
 /**
  * Click-or-drag range selection on a time histogram.
  *
@@ -62,13 +179,33 @@ function toLabel(state?: HistogramPointerState | null): string | null {
  *   click waits DOUBLE_CLICK_DISAMBIGUATION_MS and a second press or the
  *   double-click cancels it. An unzoomed chart has no double-click gesture
  *   and zooms at once.
+ * - On a zoomed chart the second press of a double-click is the zoom-out
+ *   and nothing else, and it zooms out even when the browser never sends
+ *   the `dblclick` (see useDoubleClickReset). That is what happens when the
+ *   chart's new bars land during the press, which, right after a zoom, is
+ *   when readers double-click.
+ * - A press becomes a drag only once the POINTER leaves its bar, by more
+ *   than HISTOGRAM_PRESS_STILLNESS_PX. New bars landing under a pointer that
+ *   has not moved are not a drag. A press that stayed put is a click on the
+ *   bar it pressed, even if a hand's drift ended it over the neighbour;
+ *   only when the very spot it pressed shows another bar at the release
+ *   (the same place on the axis, new data) does it zoom nowhere: the bar it
+ *   pressed is no longer on the chart.
+ * - A click waiting to zoom in is dropped if the zoom ends first (Reset
+ *   zoom, the picker, an empty state's double-click): it was a zoom into
+ *   the window the reader has just left.
+ * - Only the main button selects: a right-click opens a context menu.
  *
- * The release is resolved against refs rather than render state. Recharts
- * delivers `mousemove` on the next animation frame but `mousedown` and
- * `mouseup` straight away, so a quick drag is routinely released before its
- * last move has been rendered - or before any move has arrived at all. The
- * bar under the pointer at release time, which recharts hands to the
- * `mouseup` handler, is the most current answer and wins.
+ * The release is resolved against refs rather than render state, from the
+ * bar recharts hands the `mouseup` handler, falling back to the last move.
+ * That bar is the one under the pointer now only if the host spreads
+ * `chartRootProps` onto its chart root (see the field).
+ *
+ * A press renders nothing until the pointer leaves its bar. A render under
+ * a press can take away the node it landed on (a band repainted under the
+ * pointer, say), and a press whose node is gone by the release gets no
+ * click and no dblclick - the second click of a double-click lands on the
+ * band the first one painted.
  */
 const useHistogramRangeSelection: UseHistogramRangeSelectionFunction = (
   options: HistogramRangeSelectionOptions,
@@ -76,6 +213,33 @@ const useHistogramRangeSelection: UseHistogramRangeSelectionFunction = (
   const [selectionStart, setSelectionStart] = useState<string | null>(null);
   const [selectionEnd, setSelectionEnd] = useState<string | null>(null);
   const [isDragging, setIsDragging] = useState<boolean>(false);
+  // Whether the pointer has left the pressed bar (a drag, not a click).
+  const hasLeftPressedBar: React.MutableRefObject<boolean> =
+    useRef<boolean>(false);
+  // Where the press in progress went down, when recharts said.
+  const pressClientX: React.MutableRefObject<number | null> = useRef<
+    number | null
+  >(null);
+  // The place on the axis of the bar it went down on (see toAxisIndex).
+  const pressAxisIndex: React.MutableRefObject<string | null> = useRef<
+    string | null
+  >(null);
+  /*
+   * Where the pointer was, and the bar recharts named under it, at the
+   * press or at the last move since. recharts works out the bar under the
+   * pointer again only when the pointer moves, so a report at the same
+   * spot that names another bar means new data landed under the press -
+   * however much a hand had drifted before it.
+   */
+  const lastReport: React.MutableRefObject<PointerReport> =
+    useRef<PointerReport>({ clientX: null, label: null });
+  // Whether new data landed under the press in progress (see lastReport).
+  const barsChangedUnderPress: React.MutableRefObject<boolean> =
+    useRef<boolean>(false);
+  // The page-wide mouseup listener of the press in progress, if any.
+  const releaseListener: React.MutableRefObject<
+    ((event: MouseEvent) => void) | null
+  > = useRef<((event: MouseEvent) => void) | null>(null);
 
   /*
    * The ref stays the authority on whether a selection is in progress, so a
@@ -114,6 +278,13 @@ const useHistogramRangeSelection: UseHistogramRangeSelectionFunction = (
     setSelectionEnd(null);
   }, []);
 
+  const stopListeningForRelease: () => void = useCallback((): void => {
+    if (releaseListener.current) {
+      window.removeEventListener("mouseup", releaseListener.current);
+      releaseListener.current = null;
+    }
+  }, []);
+
   const cancelPendingClick: () => boolean = useCallback((): boolean => {
     if (pendingClick.current === null) {
       return false;
@@ -127,54 +298,296 @@ const useHistogramRangeSelection: UseHistogramRangeSelectionFunction = (
   useEffect(() => {
     return () => {
       cancelPendingClick();
+      stopListeningForRelease();
     };
-  }, [cancelPendingClick]);
+  }, [cancelPendingClick, stopListeningForRelease]);
 
-  const onMouseDown: (state?: HistogramPointerState | null) => void =
-    useCallback(
-      (state?: HistogramPointerState | null): void => {
-        const label: string | null = toLabel(state);
+  /*
+   * The zoom-out, while the chart offers one: the click waiting to zoom in
+   * goes, and so does its band.
+   */
+  const zoomOut: (() => void) | undefined = onZoomOut
+    ? (): void => {
+        cancelPendingClick();
+        clearSelection();
+        onZoomOut();
+      }
+    : undefined;
+  const doubleClickReset: DoubleClickReset = useDoubleClickReset(zoomOut);
 
-        if (!canSelect || !label) {
-          return;
-        }
+  /*
+   * A click waiting to zoom in was made on a zoomed chart. If the zoom ends
+   * by another way first - Reset zoom, the picker, an empty state's own
+   * double-click - it must not zoom back in a moment after the reader left.
+   * Its band goes too, and so does one a double-click's second press kept
+   * for a zoom-out that is no longer coming; a drag's band stays.
+   */
+  const offersZoomOut: boolean = Boolean(onZoomOut);
+
+  useEffect(() => {
+    if (offersZoomOut) {
+      return;
+    }
+
+    cancelPendingClick();
+
+    if (!isSelecting.current) {
+      clearSelection();
+    }
+  }, [offersZoomOut, cancelPendingClick, clearSelection]);
+
+  /*
+   * Whether the pointer has left the spot the press went down on. Without
+   * positions to go by (a caller that hands no event), it has: any change
+   * of bar counts, as it always did.
+   */
+  const hasPointerMoved: (event?: ChartPointerEvent | null) => boolean =
+    useCallback((event?: ChartPointerEvent | null): boolean => {
+      const clientX: number | undefined = event?.clientX;
+
+      if (pressClientX.current === null || typeof clientX !== "number") {
+        return true;
+      }
+
+      return (
+        Math.abs(clientX - pressClientX.current) > HISTOGRAM_PRESS_STILLNESS_PX
+      );
+    }, []);
+
+  /*
+   * Takes in what recharts reports during the press (a move, the release):
+   * the bar it names at a spot it last named another bar at is new data.
+   * Without positions to go by, nothing is concluded.
+   */
+  const noteReport: (
+    label: string | null,
+    event?: ChartPointerEvent | null,
+  ) => void = useCallback(
+    (label: string | null, event?: ChartPointerEvent | null): void => {
+      const clientX: number | undefined = event?.clientX;
+
+      if (typeof clientX !== "number") {
+        return;
+      }
+
+      const previous: PointerReport = lastReport.current;
+
+      if (
+        previous.clientX === clientX &&
+        previous.label !== null &&
+        label !== null &&
+        label !== previous.label
+      ) {
+        barsChangedUnderPress.current = true;
+      }
 
-        // A second press before the first click zoomed replaces it.
+      lastReport.current = { clientX: clientX, label: label };
+    },
+    [],
+  );
+
+  /*
+   * The page-wide release listener is added by a press and calls the
+   * newest onMouseUp, whatever the host re-rendered with meanwhile.
+   */
+  const onMouseUpRef: React.MutableRefObject<
+    (
+      state?: HistogramPointerState | null,
+      event?: ChartPointerEvent | null,
+    ) => void
+  > = useRef<
+    (
+      state?: HistogramPointerState | null,
+      event?: ChartPointerEvent | null,
+    ) => void
+  >(() => {});
+
+  /*
+   * Readers routinely drag past the edge of a 120px-tall chart and let go
+   * outside it, where the chart's own mouseup never fires. Listen on the
+   * page until the press ends; a release over the chart reaches the
+   * chart's handler first, which removes this listener before the page
+   * hears it. The page's release carries no bar, but it does carry where
+   * the pointer is and the click count.
+   */
+  const listenForReleaseOffChart: () => void = useCallback((): void => {
+    stopListeningForRelease();
+    const finishPressOutsideChart: (event: MouseEvent) => void = (
+      event: MouseEvent,
+    ): void => {
+      onMouseUpRef.current(null, event);
+    };
+    releaseListener.current = finishPressOutsideChart;
+    window.addEventListener("mouseup", finishPressOutsideChart);
+  }, [stopListeningForRelease]);
+
+  const onMouseDown: (
+    state?: HistogramPointerState | null,
+    event?: ChartPointerEvent | null,
+  ) => void = useCallback(
+    (
+      state?: HistogramPointerState | null,
+      event?: ChartPointerEvent | null,
+    ): void => {
+      /*
+       * The second press of a double-click on a zoomed chart: the zoom-out,
+       * on its release, wherever that is (the page hears a release off the
+       * chart, as for a drag below). The first click must not zoom in; its
+       * band stays until the zoom-out clears it, because this press may
+       * have landed on it and a render now would take that node away.
+       */
+      if (doubleClickReset.onPress(event)) {
         cancelPendingClick();
+        isSelecting.current = false;
+        listenForReleaseOffChart();
+        return;
+      }
 
-        isSelecting.current = true;
-        startLabel.current = label;
-        endLabel.current = null;
-        setIsDragging(true);
-        setSelectionStart(label);
-        setSelectionEnd(null);
-      },
-      [canSelect, cancelPendingClick],
-    );
+      const label: string | null = toLabel(state);
+
+      if (!canSelect || !label) {
+        return;
+      }
+
+      // Only the main button selects: a right-click opens a context menu.
+      if (event && typeof event.button === "number" && event.button > 0) {
+        return;
+      }
 
-  const onMouseMove: (state?: HistogramPointerState | null) => void =
-    useCallback((state?: HistogramPointerState | null): void => {
+      /*
+       * A second press before the first click zoomed replaces it. The
+       * band that click painted stays until this press ends: this may be
+       * the second click of a double-click, landing on that band.
+       */
+      cancelPendingClick();
+
+      isSelecting.current = true;
+      hasLeftPressedBar.current = false;
+      startLabel.current = label;
+      endLabel.current = null;
+      pressClientX.current =
+        typeof event?.clientX === "number" ? event.clientX : null;
+      pressAxisIndex.current = toAxisIndex(state);
+      lastReport.current = { clientX: pressClientX.current, label: label };
+      barsChangedUnderPress.current = false;
+
+      listenForReleaseOffChart();
+    },
+    [canSelect, cancelPendingClick, doubleClickReset, listenForReleaseOffChart],
+  );
+
+  const onMouseMove: (
+    state?: HistogramPointerState | null,
+    event?: ChartPointerEvent | null,
+  ) => void = useCallback(
+    (
+      state?: HistogramPointerState | null,
+      event?: ChartPointerEvent | null,
+    ): void => {
       const label: string | null = toLabel(state);
+      const from: string | null = startLabel.current;
 
-      if (!isSelecting.current || !label) {
+      if (!isSelecting.current || !from) {
         return;
       }
 
+      noteReport(label, event);
+
+      if (!label) {
+        return;
+      }
+
+      if (!hasLeftPressedBar.current) {
+        // Still on the pressed bar: a click so far, so paint nothing.
+        if (label === from) {
+          endLabel.current = label;
+          return;
+        }
+
+        /*
+         * Another bar under a pointer that has not really moved: new bars
+         * landed under the press, or a hand's drift crossed the edge of the
+         * bar it pressed. Not a drag.
+         */
+        if (!hasPointerMoved(event)) {
+          return;
+        }
+      }
+
       endLabel.current = label;
-      setSelectionEnd(label);
-    }, []);
+      hasLeftPressedBar.current = true;
+      const [first, last]: [string, string] = inTimeOrder(from, label);
+      setSelectionStart(first);
+      setSelectionEnd(last);
+      setIsDragging(true);
+    },
+    [hasPointerMoved, noteReport],
+  );
+
+  const onMouseUp: (
+    state?: HistogramPointerState | null,
+    event?: ChartPointerEvent | null,
+  ) => void = useCallback(
+    (
+      state?: HistogramPointerState | null,
+      event?: ChartPointerEvent | null,
+    ): void => {
+      // The end of a double-click's second press: the zoom-out, nothing else.
+      if (doubleClickReset.onRelease(event)) {
+        stopListeningForRelease();
+
+        /*
+         * Ended by a later click's release, its own having never come: no
+         * zoom-out follows, so the band the first click painted, kept for
+         * one, goes now.
+         */
+        if (!doubleClickReset.willReset()) {
+          clearSelection();
+        }
+        return;
+      }
 
-  const onMouseUp: (state?: HistogramPointerState | null) => void = useCallback(
-    (state?: HistogramPointerState | null): void => {
       if (!isSelecting.current) {
         return;
       }
 
       isSelecting.current = false;
+      stopListeningForRelease();
       setIsDragging(false);
 
       const from: string | null = startLabel.current;
-      const to: string | null = toLabel(state) || endLabel.current || from;
+      const releaseLabel: string | null = toLabel(state);
+      let to: string | null = from;
+
+      noteReport(releaseLabel, event);
+
+      if (hasLeftPressedBar.current || hasPointerMoved(event)) {
+        // A drag, or a flick released before any of its moves came in.
+        to = releaseLabel || endLabel.current || from;
+      } else if (releaseLabel !== null && releaseLabel !== from) {
+        /*
+         * The pointer stayed put, yet another bar is under it. When a bar
+         * changed under the pointer without it moving (see lastReport), or
+         * the spot on the axis it pressed now holds another bar, the
+         * chart's data changed during the press and the pressed bar is
+         * gone (recharts also clamps a stale spot onto the last bar of
+         * shorter data): not a drag the reader never made, nor a zoom into
+         * a bar that is no longer shown.
+         */
+        const sameSpotOnAxis: boolean =
+          pressAxisIndex.current !== null &&
+          toAxisIndex(state) === pressAxisIndex.current;
+
+        if (barsChangedUnderPress.current || sameSpotOnAxis) {
+          clearSelection();
+          return;
+        }
+      }
+
+      /*
+       * Otherwise a press that stayed put is a click on the bar it pressed,
+       * even when a hand's drift let it go over the next one.
+       */
 
       if (!from || !to) {
         clearSelection();
@@ -209,6 +622,7 @@ const useHistogramRangeSelection: UseHistogramRangeSelectionFunction = (
        * to open.
        */
       endLabel.current = to;
+      setSelectionStart(from);
       setSelectionEnd(to);
 
       pendingClick.current = setTimeout(() => {
@@ -217,38 +631,54 @@ const useHistogramRangeSelection: UseHistogramRangeSelectionFunction = (
         onTimeRangeSelectRef.current?.(selected.startTime, selected.endTime);
       }, DOUBLE_CLICK_DISAMBIGUATION_MS);
     },
-    [bucketIntervalMs, clearSelection, onZoomOut],
+    [
+      bucketIntervalMs,
+      clearSelection,
+      doubleClickReset,
+      hasPointerMoved,
+      noteReport,
+      onZoomOut,
+      stopListeningForRelease,
+    ],
   );
+  onMouseUpRef.current = onMouseUp;
 
   const onDoubleClick: () => void = useCallback((): void => {
+    // Neither click of a double-click zooms in, whatever else it does.
     if (cancelPendingClick()) {
       clearSelection();
     }
 
-    onZoomOut?.();
-  }, [cancelPendingClick, clearSelection, onZoomOut]);
+    doubleClickReset.onDoubleClick();
+  }, [cancelPendingClick, clearSelection, doubleClickReset]);
 
   /*
-   * Readers routinely drag past the edge of a 120px-tall chart and let go
-   * outside it, where the chart's own mouseup never fires. Without this the
-   * drag would never end: the selection band would stay painted and the
-   * tooltip would stay suppressed until the next click.
+   * A press on a box standing in for the chart. It has no bars to select;
+   * only the second press of a double-click counts, and its release - on
+   * the chart that replaced the box by then, or anywhere on the page -
+   * zooms out as the chart's own would.
    */
-  useEffect(() => {
-    if (!isDragging) {
-      return undefined;
-    }
-
-    const finishDragOutsideChart: () => void = (): void => {
-      onMouseUp(null);
-    };
+  const onPlaceholderMouseDown: (event: React.MouseEvent<HTMLElement>) => void =
+    useCallback(
+      (event: React.MouseEvent<HTMLElement>): void => {
+        if (!doubleClickReset.onPress(event)) {
+          return;
+        }
 
-    window.addEventListener("mouseup", finishDragOutsideChart);
+        cancelPendingClick();
+        isSelecting.current = false;
+        listenForReleaseOffChart();
+      },
+      [cancelPendingClick, doubleClickReset, listenForReleaseOffChart],
+    );
 
-    return () => {
-      window.removeEventListener("mouseup", finishDragOutsideChart);
-    };
-  }, [isDragging, onMouseUp]);
+  const placeholderProps: HistogramPlaceholderProps =
+    useMemo((): HistogramPlaceholderProps => {
+      return {
+        onMouseDown: onPlaceholderMouseDown,
+        onDoubleClick: onDoubleClick,
+      };
+    }, [onPlaceholderMouseDown, onDoubleClick]);
 
   return {
     selectionStart: selectionStart,
@@ -259,10 +689,14 @@ const useHistogramRangeSelection: UseHistogramRangeSelectionFunction = (
       typeof bucketIntervalMs === "number" &&
       Number.isFinite(bucketIntervalMs) &&
       bucketIntervalMs > 0,
+    chartRootProps: canSelect
+      ? SELECTABLE_CHART_ROOT_PROPS
+      : INERT_CHART_ROOT_PROPS,
     onMouseDown: onMouseDown,
     onMouseMove: onMouseMove,
     onMouseUp: onMouseUp,
     onDoubleClick: onDoubleClick,
+    placeholderProps: placeholderProps,
   };
 };