@oneuptime/common 14.0.7 → 14.0.9

package/UI/Components/Charts/TimeRangeZoom/ResetTimeRangeZoomButton.tsx

@@ -0,0 +1,70 @@
+import React, { FunctionComponent, ReactElement } from "react";
+import IconProp from "../../../../Types/Icon/IconProp";
+import RangeStartAndEndDateTime from "../../../../Types/Time/RangeStartAndEndDateTime";
+import TimeRange from "../../../../Types/Time/TimeRange";
+import Icon from "../../Icon/Icon";
+import {
+  ChartTimeRangeZoomContextValue,
+  isTimeRangeZoomFor,
+  useChartTimeRangeZoom,
+} from "./TimeRangeZoomContext";
+
+export const RESET_TIME_RANGE_ZOOM_BUTTON_TEST_ID: string =
+  "reset-time-range-zoom";
+
+export interface ComponentProps {
+  className?: string | undefined;
+  /*
+   * The range of the picker or card this button sits beside. The button
+   * then shows only for a zoom of THAT range: a time-series viewer or a
+   * card nested in a zoomed page has a range of its own, and its button
+   * must not reset the page behind it.
+   */
+  forTimeRange?: RangeStartAndEndDateTime | undefined;
+}
+
+/**
+ * "Reset zoom", shown only while the enclosing page is zoomed. The same
+ * thing a double-click on any chart does, for readers who do not know that
+ * gesture and for keyboard users, who cannot perform it.
+ *
+ * Renders nothing outside a zoomable page or while the page is not zoomed.
+ */
+const ResetTimeRangeZoomButton: FunctionComponent<ComponentProps> = (
+  props: ComponentProps,
+): ReactElement | null => {
+  const zoom: ChartTimeRangeZoomContextValue | null = useChartTimeRangeZoom();
+
+  if (!zoom || !zoom.isZoomed || !zoom.onTimeRangeReset) {
+    return null;
+  }
+
+  if (props.forTimeRange && !isTimeRangeZoomFor(zoom, props.forTimeRange)) {
+    return null;
+  }
+
+  const onTimeRangeReset: () => void = zoom.onTimeRangeReset;
+  const previousRange: TimeRange | undefined = zoom.rangeBeforeZoom?.range;
+  const title: string =
+    previousRange && previousRange !== TimeRange.CUSTOM
+      ? `Go back to ${previousRange}, the time range before the zoom`
+      : "Go back to the time range before the zoom";
+
+  return (
+    <button
+      type="button"
+      data-testid={RESET_TIME_RANGE_ZOOM_BUTTON_TEST_ID}
+      className={`inline-flex shrink-0 items-center gap-1 whitespace-nowrap rounded-md px-1.5 py-1 text-xs font-medium text-indigo-600 transition-colors hover:bg-indigo-50 hover:text-indigo-700 focus:outline-none focus-visible:ring-2 focus-visible:ring-indigo-400 ${props.className || ""}`}
+      title={title}
+      aria-label="Reset zoom"
+      onClick={() => {
+        onTimeRangeReset();
+      }}
+    >
+      <Icon icon={IconProp.MagnifyingGlassMinus} className="h-3.5 w-3.5" />
+      Reset zoom
+    </button>
+  );
+};
+
+export default ResetTimeRangeZoomButton;

package/UI/Components/Charts/TimeRangeZoom/TimeRangeZoomContext.tsx

@@ -0,0 +1,226 @@
+import React, {
+  FunctionComponent,
+  ReactElement,
+  ReactNode,
+  useContext,
+  useMemo,
+  useRef,
+} from "react";
+import RangeStartAndEndDateTime from "../../../../Types/Time/RangeStartAndEndDateTime";
+import useTimeRangeZoom, { TimeRangeZoom } from "./UseTimeRangeZoom";
+import TimeRangeZoomUtil from "./TimeRangeZoomUtil";
+
+/**
+ * What a chart needs to take part in page-wide drag-to-zoom. Handed down by
+ * a page (see TimeRangeZoomScope) so that every time-series chart below it
+ * zooms the page instead of doing nothing, without threading two callbacks
+ * through every card, tab and wrapper in between.
+ */
+export interface ChartTimeRangeZoomContextValue {
+  /** A drag-selection on a chart: zooms the page to [startTime, endTime). */
+  onTimeRangeSelect: (startTime: Date, endTime: Date) => void;
+  /*
+   * A double-click on a chart: undoes the zoom. Set only while the page is
+   * zoomed. Charts hold every single click open for a moment while it is
+   * set (to tell it apart from a double-click), so offering it while there
+   * is nothing to undo would slow every click down for nothing.
+   */
+  onTimeRangeReset: (() => void) | undefined;
+  isZoomed: boolean;
+  /** The range a reset returns to; null while the page is not zoomed. */
+  rangeBeforeZoom: RangeStartAndEndDateTime | null;
+  /*
+   * The range this zoom works over right now (the page's current range),
+   * or null when the zoom did not say. A control that owns a range of its
+   * own uses it to tell whether this zoom is about ITS range: a viewer or a
+   * card nested in a zoomed page must not offer to reset the page.
+   */
+  timeRange: RangeStartAndEndDateTime | null;
+}
+
+const ChartTimeRangeZoomContext: React.Context<ChartTimeRangeZoomContextValue | null> =
+  React.createContext<ChartTimeRangeZoomContextValue | null>(null);
+
+/** The zoom the nearest page (or panel) offers, or null when none does. */
+export const useChartTimeRangeZoom: () => ChartTimeRangeZoomContextValue | null =
+  (): ChartTimeRangeZoomContextValue | null => {
+    return useContext(ChartTimeRangeZoomContext);
+  };
+
+export interface TimeRangeZoomProviderProps {
+  /*
+   * The zoom to offer the charts below. null withdraws any zoom offered
+   * further up: for a panel whose charts do not follow the page's range.
+   */
+  zoom: TimeRangeZoom | null;
+  children: ReactNode;
+}
+
+/**
+ * Offers a zoom (from useTimeRangeZoom) to every chart below. Use it when
+ * the page needs the zoom itself too, e.g. to show a reset button of its
+ * own; otherwise TimeRangeZoomScope is the one-liner.
+ */
+export const TimeRangeZoomProvider: FunctionComponent<
+  TimeRangeZoomProviderProps
+> = (props: TimeRangeZoomProviderProps): ReactElement => {
+  const zoom: TimeRangeZoom | null = props.zoom;
+  const onTimeRangeSelect: ((startTime: Date, endTime: Date) => void) | null =
+    zoom ? zoom.zoomToTimeRange : null;
+  const resetZoom: (() => void) | null = zoom ? zoom.resetZoom : null;
+  const isZoomed: boolean = Boolean(zoom?.isZoomed);
+  const rangeBeforeZoom: RangeStartAndEndDateTime | null =
+    zoom?.rangeBeforeZoom || null;
+  /*
+   * Kept by value: a page that builds its range inline would otherwise
+   * hand every chart a new context on every render.
+   */
+  const stableTimeRange: React.MutableRefObject<RangeStartAndEndDateTime | null> =
+    useRef<RangeStartAndEndDateTime | null>(zoom?.timeRange || null);
+  if (
+    !TimeRangeZoomUtil.isSameRange(
+      stableTimeRange.current,
+      zoom?.timeRange || null,
+    )
+  ) {
+    stableTimeRange.current = zoom?.timeRange || null;
+  }
+  const timeRange: RangeStartAndEndDateTime | null = stableTimeRange.current;
+
+  const value: ChartTimeRangeZoomContextValue | null =
+    useMemo((): ChartTimeRangeZoomContextValue | null => {
+      if (!onTimeRangeSelect || !resetZoom) {
+        return null;
+      }
+
+      return {
+        onTimeRangeSelect: onTimeRangeSelect,
+        onTimeRangeReset: isZoomed ? resetZoom : undefined,
+        isZoomed: isZoomed,
+        rangeBeforeZoom: rangeBeforeZoom,
+        timeRange: timeRange,
+      };
+    }, [onTimeRangeSelect, resetZoom, isZoomed, rangeBeforeZoom, timeRange]);
+
+  return (
+    <ChartTimeRangeZoomContext.Provider value={value}>
+      {props.children}
+    </ChartTimeRangeZoomContext.Provider>
+  );
+};
+
+export interface TimeRangeZoomScopeProps {
+  /** The range the page is showing right now. */
+  timeRange: RangeStartAndEndDateTime;
+  /** The page's own setter for it. */
+  onTimeRangeChange: (timeRange: RangeStartAndEndDateTime) => void;
+  children: ReactNode;
+}
+
+/**
+ * Makes every time-series chart inside it zoom the page: a drag on any of
+ * them sets the page's range to the window dragged out, a double-click on
+ * any of them puts the previous range back, and the page's time picker
+ * offers a "Reset zoom" button while it is zoomed.
+ *
+ *   <TimeRangeZoomScope timeRange={timeRange} onTimeRangeChange={setTimeRange}>
+ *     ...the page...
+ *   </TimeRangeZoomScope>
+ *
+ * Wrap the page's picker too, so it can show the reset button.
+ */
+export const TimeRangeZoomScope: FunctionComponent<TimeRangeZoomScopeProps> = (
+  props: TimeRangeZoomScopeProps,
+): ReactElement => {
+  const zoom: TimeRangeZoom = useTimeRangeZoom({
+    timeRange: props.timeRange,
+    onTimeRangeChange: props.onTimeRangeChange,
+  });
+
+  return (
+    <TimeRangeZoomProvider zoom={zoom}>{props.children}</TimeRangeZoomProvider>
+  );
+};
+
+/**
+ * Whether a zoom is over the given range. A zoom that did not say which
+ * range it works over is taken to be over any; see
+ * ChartTimeRangeZoomContextValue.timeRange.
+ */
+export const isTimeRangeZoomFor: (
+  zoom: ChartTimeRangeZoomContextValue | null,
+  timeRange: RangeStartAndEndDateTime,
+) => boolean = (
+  zoom: ChartTimeRangeZoomContextValue | null,
+  timeRange: RangeStartAndEndDateTime,
+): boolean => {
+  if (!zoom) {
+    return false;
+  }
+
+  if (!zoom.timeRange) {
+    return true;
+  }
+
+  return TimeRangeZoomUtil.isSameRange(zoom.timeRange, timeRange);
+};
+
+export interface ChartTimeRangeZoomHandlers {
+  onTimeRangeSelect: ((startTime: Date, endTime: Date) => void) | undefined;
+  onTimeRangeReset: (() => void) | undefined;
+}
+
+export interface ResolveChartTimeRangeZoomInput {
+  /** Handlers the chart's host passed explicitly. They always win. */
+  onTimeRangeSelect?: ((startTime: Date, endTime: Date) => void) | undefined;
+  onTimeRangeReset?: (() => void) | undefined;
+  /*
+   * Only a chart whose x-axis is time can be zoomed: a window dragged
+   * across categories ("top services") is not a time range.
+   */
+  isTimeAxis: boolean;
+  /** The chart opted out of zooming altogether. */
+  disableTimeRangeZoom?: boolean | undefined;
+  /** What the enclosing page offers (useChartTimeRangeZoom). */
+  pageZoom: ChartTimeRangeZoomContextValue | null;
+}
+
+/**
+ * Which zoom handlers a chart ends up with.
+ *
+ * - disableTimeRangeZoom: none at all.
+ * - A host that passes either handler owns zooming for that chart: it gets
+ *   exactly what the host passed. A host that zooms its own way also resets
+ *   its own way; borrowing the page's reset would undo a zoom the chart did
+ *   not make, and borrowing the page's zoom would make a reset-only chart
+ *   (a dashboard bar panel) retime something its host does not know about.
+ * - Otherwise a time-axis chart takes the page's zoom, if the page offers
+ *   one.
+ */
+export const resolveChartTimeRangeZoom: (
+  input: ResolveChartTimeRangeZoomInput,
+) => ChartTimeRangeZoomHandlers = (
+  input: ResolveChartTimeRangeZoomInput,
+): ChartTimeRangeZoomHandlers => {
+  if (input.disableTimeRangeZoom) {
+    return { onTimeRangeSelect: undefined, onTimeRangeReset: undefined };
+  }
+
+  if (input.onTimeRangeSelect || input.onTimeRangeReset) {
+    return {
+      onTimeRangeSelect: input.onTimeRangeSelect,
+      onTimeRangeReset: input.onTimeRangeReset,
+    };
+  }
+
+  if (input.isTimeAxis && input.pageZoom) {
+    return {
+      onTimeRangeSelect: input.pageZoom.onTimeRangeSelect,
+      onTimeRangeReset: input.pageZoom.onTimeRangeReset,
+    };
+  }
+
+  return { onTimeRangeSelect: undefined, onTimeRangeReset: undefined };
+};
+
+export default ChartTimeRangeZoomContext;

package/UI/Components/Charts/TimeRangeZoom/TimeRangeZoomHint.tsx

@@ -0,0 +1,73 @@
+import React, { FunctionComponent, ReactElement } from "react";
+import {
+  ChartTimeRangeZoomContextValue,
+  useChartTimeRangeZoom,
+} from "./TimeRangeZoomContext";
+
+export const TIME_RANGE_ZOOM_HINT_TEST_ID: string = "time-range-zoom-hint";
+
+/*
+ * The class a chart card puts on its root so the hint can reveal itself on
+ * hover. A NAMED Tailwind group on purpose: a plain `group` on the card
+ * would also light up every descendant's own `group-hover:` styles - the
+ * chart legends darken their labels on `group-hover` - whenever the pointer
+ * is anywhere over the card.
+ */
+export const TIME_RANGE_ZOOM_HINT_GROUP_CLASS: string = "group/zoomhint";
+
+export const TIME_RANGE_ZOOM_HINT_TEXT: string = "Drag to zoom";
+export const TIME_RANGE_ZOOM_HINT_RESET_TEXT: string = "Double-click to reset";
+
+/*
+ * How a revealOnHover hint shows itself: while the pointer is over the card,
+ * and while something in the card has KEYBOARD focus. Not on any focus
+ * (focus-within): a press on a chart focuses recharts' own layers, which
+ * keep that focus after the drag, so the hint stayed up over a card the
+ * pointer had long left. :focus-visible is the focus a keyboard gives.
+ */
+export const TIME_RANGE_ZOOM_HINT_REVEAL_CLASSES: string =
+  "opacity-0 transition-opacity group-hover/zoomhint:opacity-100 group-has-[:focus-visible]/zoomhint:opacity-100";
+
+export interface ComponentProps {
+  /*
+   * Show the hint only while the pointer is over the card (an ancestor
+   * with TIME_RANGE_ZOOM_HINT_GROUP_CLASS), or while the reader tabs
+   * through it. Keeps a row of small chart cards uncluttered; the hint
+   * appears exactly when the reader could drag.
+   */
+  revealOnHover?: boolean | undefined;
+  className?: string | undefined;
+}
+
+/**
+ * Names the drag-to-zoom gesture in a chart card's header whenever the
+ * enclosing page zooms: "Drag to zoom", and "Double-click to reset" while a
+ * zoom is active. The words are short on purpose - four of these cards can
+ * share a row. Renders nothing outside a zoomable page.
+ */
+const TimeRangeZoomHint: FunctionComponent<ComponentProps> = (
+  props: ComponentProps,
+): ReactElement | null => {
+  const zoom: ChartTimeRangeZoomContextValue | null = useChartTimeRangeZoom();
+
+  if (!zoom) {
+    return null;
+  }
+
+  const revealClassName: string = props.revealOnHover
+    ? TIME_RANGE_ZOOM_HINT_REVEAL_CLASSES
+    : "";
+
+  return (
+    <span
+      data-testid={TIME_RANGE_ZOOM_HINT_TEST_ID}
+      className={`shrink-0 whitespace-nowrap text-[10px] text-gray-400 ${revealClassName} ${props.className || ""}`}
+    >
+      {zoom.onTimeRangeReset
+        ? TIME_RANGE_ZOOM_HINT_RESET_TEXT
+        : TIME_RANGE_ZOOM_HINT_TEXT}
+    </span>
+  );
+};
+
+export default TimeRangeZoomHint;

package/UI/Components/Charts/TimeRangeZoom/TimeRangeZoomUtil.ts

@@ -0,0 +1,163 @@
+import InBetween from "../../../../Types/BaseDatabase/InBetween";
+import OneUptimeDate from "../../../../Types/Date";
+import RangeStartAndEndDateTime, {
+  RangeStartAndEndDateTimeUtil,
+} from "../../../../Types/Time/RangeStartAndEndDateTime";
+import TimeRange from "../../../../Types/Time/TimeRange";
+import {
+  HistogramSelectionWindow,
+  clampHistogramSelectionToWindowEnd,
+} from "../Utils/HistogramSelection";
+
+export interface TimeRangeZoomSelection {
+  /** One edge of the window dragged out on a chart. */
+  startTime: Date;
+  /** The other edge. A right-to-left drag hands them over reversed. */
+  endTime: Date;
+  /*
+   * The range the page is on when the drag lands. The zoom never runs past
+   * its end; see getZoomedRange.
+   */
+  currentRange?: RangeStartAndEndDateTime | undefined;
+}
+
+type ToEpochMsFunction = (value: unknown) => number;
+
+/*
+ * A range restored from a URL, a saved view or local storage can carry its
+ * dates as ISO strings despite the type, so read every date through
+ * OneUptimeDate.fromString. NaN for anything that is not a date.
+ */
+const toEpochMs: ToEpochMsFunction = (value: unknown): number => {
+  if (value === undefined || value === null || value === "") {
+    return Number.NaN;
+  }
+
+  try {
+    return OneUptimeDate.fromString(value as Date).getTime();
+  } catch {
+    return Number.NaN;
+  }
+};
+
+/**
+ * The pure half of page-wide drag-to-zoom: what window a drag zooms to, and
+ * whether the page is still on that window.
+ */
+export default class TimeRangeZoomUtil {
+  /**
+   * The custom range a drag-selection zooms the page to, or null when the
+   * selection is not a usable window.
+   *
+   * - A drag right-to-left is the same window as left-to-right.
+   * - A zero-width or invalid selection is not a window: a drag that never
+   *   left its starting bucket can hand back one. Zooming to it would show
+   *   nothing at all and spend a page-wide refetch doing so.
+   * - The zoom never runs past the end of the range the page is on. The
+   *   newest bucket is usually still filling up, so taken whole it reaches
+   *   past "now" and would open a window that ends in the future (the same
+   *   rule the log and trace histograms follow; see
+   *   clampHistogramSelectionToWindowEnd).
+   */
+  public static getZoomedRange(
+    selection: TimeRangeZoomSelection,
+  ): RangeStartAndEndDateTime | null {
+    const startMs: number = toEpochMs(selection.startTime);
+    const endMs: number = toEpochMs(selection.endTime);
+
+    if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) {
+      return null;
+    }
+
+    let window: HistogramSelectionWindow = {
+      startTime: new Date(Math.min(startMs, endMs)),
+      endTime: new Date(Math.max(startMs, endMs)),
+    };
+
+    if (window.startTime.getTime() === window.endTime.getTime()) {
+      return null;
+    }
+
+    if (selection.currentRange) {
+      const currentWindow: InBetween<Date> =
+        RangeStartAndEndDateTimeUtil.getStartAndEndDate(selection.currentRange);
+      const currentWindowEndMs: number = toEpochMs(currentWindow.endValue);
+
+      if (Number.isFinite(currentWindowEndMs)) {
+        window = clampHistogramSelectionToWindowEnd(
+          window,
+          new Date(currentWindowEndMs),
+        );
+      }
+    }
+
+    return {
+      range: TimeRange.CUSTOM,
+      startAndEndDate: new InBetween<Date>(window.startTime, window.endTime),
+    };
+  }
+
+  /**
+   * Whether two ranges describe the same window. A relative range ("past
+   * hour") is the same range whatever dates it resolved to last time; a
+   * custom range is the same when both edges are the same instant, however
+   * they are represented.
+   */
+  public static isSameRange(
+    first: RangeStartAndEndDateTime | null | undefined,
+    second: RangeStartAndEndDateTime | null | undefined,
+  ): boolean {
+    if (!first || !second) {
+      return !first && !second;
+    }
+
+    if (first === second) {
+      return true;
+    }
+
+    if (first.range !== second.range) {
+      return false;
+    }
+
+    if (first.range !== TimeRange.CUSTOM) {
+      return true;
+    }
+
+    const firstStartMs: number = toEpochMs(first.startAndEndDate?.startValue);
+    const firstEndMs: number = toEpochMs(first.startAndEndDate?.endValue);
+    const secondStartMs: number = toEpochMs(second.startAndEndDate?.startValue);
+    const secondEndMs: number = toEpochMs(second.startAndEndDate?.endValue);
+
+    return (
+      Number.isFinite(firstStartMs) &&
+      Number.isFinite(firstEndMs) &&
+      firstStartMs === secondStartMs &&
+      firstEndMs === secondEndMs
+    );
+  }
+
+  /**
+   * A range's value as a string, for an effect to depend on: a page that
+   * re-states its range in a new but equal object must not look like a
+   * move. Two ranges isSameRange calls the same get the same key: a
+   * relative range is keyed by its preset alone, whatever it last resolved
+   * to, and a custom one by the instants of its edges.
+   */
+  public static getRangeKey(
+    range: RangeStartAndEndDateTime | null | undefined,
+  ): string {
+    if (!range) {
+      return "";
+    }
+
+    if (range.range !== TimeRange.CUSTOM) {
+      return range.range;
+    }
+
+    return [
+      range.range,
+      toEpochMs(range.startAndEndDate?.startValue),
+      toEpochMs(range.startAndEndDate?.endValue),
+    ].join("|");
+  }
+}