@oneuptime/common 11.7.3 → 12.0.0

package/UI/Types/UseAnchoredFieldPopup.ts

@@ -0,0 +1,321 @@
+import React, {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+
+/*
+ * Form field popups (colour pickers, icon grids, ...) are rendered inside
+ * Modal's scrolling body, which clips absolutely positioned children. This hook
+ * drives a popup that is portalled into document.body and positioned `fixed`
+ * against its anchor, so it escapes the clipping container entirely.
+ *
+ * It mirrors the menu placement rules used by EntityDropdown: prefer below the
+ * anchor, flip above when there is not enough room, and clamp horizontally to
+ * the viewport.
+ */
+
+const POPUP_GAP_PX: number = 4;
+const POPUP_VIEWPORT_PADDING_PX: number = 8;
+const POPUP_MIN_USEFUL_HEIGHT_PX: number = 160;
+
+const FOCUSABLE_SELECTOR: string =
+  'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
+
+export interface AnchoredFieldPopupPosition {
+  bottom: number | undefined;
+  left: number;
+  maxHeight: number;
+  top: number | undefined;
+  width: number;
+}
+
+export interface AnchoredFieldPopupOptions {
+  // Intrinsic width of the popup, used to clamp it inside the viewport.
+  popupWidth: number;
+  popupMaxHeight: number;
+}
+
+export interface AnchoredFieldPopup {
+  anchorRef: React.MutableRefObject<HTMLDivElement | null>;
+  popupRef: React.MutableRefObject<HTMLDivElement | null>;
+  isPopupOpen: boolean;
+  popupPosition: AnchoredFieldPopupPosition | null;
+  portalTarget: HTMLElement | null;
+  closePopup: (shouldReturnFocus?: boolean) => void;
+  togglePopup: () => void;
+}
+
+type GetFocusableElementsFunction = (
+  container: HTMLElement,
+) => Array<HTMLElement>;
+
+const getFocusableElements: GetFocusableElementsFunction = (
+  container: HTMLElement,
+): Array<HTMLElement> => {
+  return Array.from(
+    container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+  ).filter((element: HTMLElement) => {
+    return (
+      !element.hasAttribute("disabled") &&
+      element.getAttribute("aria-hidden") !== "true"
+    );
+  });
+};
+
+type UseAnchoredFieldPopupFunction = (
+  options: AnchoredFieldPopupOptions,
+) => AnchoredFieldPopup;
+
+const useAnchoredFieldPopup: UseAnchoredFieldPopupFunction = (
+  options: AnchoredFieldPopupOptions,
+): AnchoredFieldPopup => {
+  const { popupWidth, popupMaxHeight } = options;
+
+  const [isPopupOpen, setIsPopupOpen] = useState<boolean>(false);
+  const [popupPosition, setPopupPosition] =
+    useState<AnchoredFieldPopupPosition | null>(null);
+
+  const anchorRef: React.MutableRefObject<HTMLDivElement | null> =
+    useRef<HTMLDivElement | null>(null);
+  const popupRef: React.MutableRefObject<HTMLDivElement | null> =
+    useRef<HTMLDivElement | null>(null);
+
+  const closePopup: (shouldReturnFocus?: boolean) => void = useCallback(
+    (shouldReturnFocus?: boolean): void => {
+      setIsPopupOpen(false);
+
+      if (!shouldReturnFocus) {
+        return;
+      }
+
+      /*
+       * The popup lives outside the modal, so on close we hand focus back to the
+       * field that opened it rather than letting it fall through to the body.
+       */
+      const anchor: HTMLDivElement | null = anchorRef.current;
+
+      if (!anchor) {
+        return;
+      }
+
+      const focusTarget: HTMLElement =
+        anchor.querySelector<HTMLElement>(FOCUSABLE_SELECTOR) || anchor;
+
+      focusTarget.focus();
+    },
+    [],
+  );
+
+  const togglePopup: () => void = useCallback((): void => {
+    setIsPopupOpen((isOpen: boolean) => {
+      return !isOpen;
+    });
+  }, []);
+
+  const updatePopupPosition: () => void = useCallback((): void => {
+    if (!anchorRef.current || typeof window === "undefined") {
+      return;
+    }
+
+    const anchorRect: DOMRect = anchorRef.current.getBoundingClientRect();
+    const availableWidth: number = Math.max(
+      0,
+      window.innerWidth - POPUP_VIEWPORT_PADDING_PX * 2,
+    );
+    const width: number = Math.min(popupWidth, availableWidth);
+    const maximumLeft: number = Math.max(
+      POPUP_VIEWPORT_PADDING_PX,
+      window.innerWidth - POPUP_VIEWPORT_PADDING_PX - width,
+    );
+    const left: number = Math.min(
+      Math.max(anchorRect.left, POPUP_VIEWPORT_PADDING_PX),
+      maximumLeft,
+    );
+    const spaceBelow: number = Math.max(
+      0,
+      window.innerHeight -
+        anchorRect.bottom -
+        POPUP_GAP_PX -
+        POPUP_VIEWPORT_PADDING_PX,
+    );
+    const spaceAbove: number = Math.max(
+      0,
+      anchorRect.top - POPUP_GAP_PX - POPUP_VIEWPORT_PADDING_PX,
+    );
+    const shouldOpenAbove: boolean =
+      spaceBelow < POPUP_MIN_USEFUL_HEIGHT_PX && spaceAbove > spaceBelow;
+    const availableHeight: number = shouldOpenAbove ? spaceAbove : spaceBelow;
+
+    setPopupPosition({
+      bottom: shouldOpenAbove
+        ? window.innerHeight - anchorRect.top + POPUP_GAP_PX
+        : undefined,
+      left,
+      maxHeight: Math.min(popupMaxHeight, availableHeight),
+      top: shouldOpenAbove ? undefined : anchorRect.bottom + POPUP_GAP_PX,
+      width,
+    });
+  }, [popupWidth, popupMaxHeight]);
+
+  useLayoutEffect(() => {
+    if (!isPopupOpen) {
+      setPopupPosition(null);
+      return;
+    }
+
+    let animationFrame: number | null = null;
+
+    const schedulePositionUpdate: () => void = (): void => {
+      if (animationFrame !== null) {
+        return;
+      }
+      animationFrame = window.requestAnimationFrame((): void => {
+        animationFrame = null;
+        updatePopupPosition();
+      });
+    };
+
+    updatePopupPosition();
+
+    /*
+     * Capture phase so scrolling the modal body - which does not bubble a scroll
+     * event to window - still repositions the popup against its anchor.
+     */
+    window.addEventListener("resize", schedulePositionUpdate);
+    document.addEventListener("scroll", schedulePositionUpdate, true);
+
+    return () => {
+      window.removeEventListener("resize", schedulePositionUpdate);
+      document.removeEventListener("scroll", schedulePositionUpdate, true);
+      if (animationFrame !== null) {
+        window.cancelAnimationFrame(animationFrame);
+      }
+    };
+  }, [isPopupOpen, updatePopupPosition]);
+
+  // Outside click. Portal aware: the popup is not a DOM child of the anchor.
+  useEffect(() => {
+    if (!isPopupOpen) {
+      return;
+    }
+
+    type HandlePointerDownFunction = (event: MouseEvent) => void;
+
+    const handlePointerDown: HandlePointerDownFunction = (
+      event: MouseEvent,
+    ): void => {
+      if (!(event.target instanceof Node)) {
+        return;
+      }
+
+      const target: Node = event.target;
+
+      if (anchorRef.current?.contains(target)) {
+        // The trigger toggles itself, so leave the state change to its handler.
+        return;
+      }
+
+      if (popupRef.current?.contains(target)) {
+        return;
+      }
+
+      closePopup(false);
+    };
+
+    document.addEventListener("mousedown", handlePointerDown, true);
+
+    return () => {
+      document.removeEventListener("mousedown", handlePointerDown, true);
+    };
+  }, [isPopupOpen, closePopup]);
+
+  useEffect(() => {
+    if (!isPopupOpen) {
+      return;
+    }
+
+    type HandleKeyDownFunction = (event: KeyboardEvent) => void;
+
+    const handleKeyDown: HandleKeyDownFunction = (
+      event: KeyboardEvent,
+    ): void => {
+      if (event.key === "Escape") {
+        /*
+         * Swallow Escape during the capture phase so Modal's document level
+         * handler never sees it. Escape dismisses this popup, not the modal.
+         */
+        event.preventDefault();
+        event.stopPropagation();
+        closePopup(true);
+        return;
+      }
+
+      if (event.key !== "Tab") {
+        return;
+      }
+
+      const popup: HTMLDivElement | null = popupRef.current;
+
+      if (!popup) {
+        return;
+      }
+
+      const focusableElements: Array<HTMLElement> = getFocusableElements(popup);
+
+      if (focusableElements.length === 0) {
+        return;
+      }
+
+      /*
+       * Modal builds its focus trap from its own subtree, so once focus is in
+       * the portalled popup it would drag focus back into the modal on every
+       * Tab. Keep Tab cycling within the popup until Escape or a selection
+       * closes it.
+       */
+      event.stopPropagation();
+
+      const firstElement: HTMLElement = focusableElements[0]!;
+      const lastElement: HTMLElement =
+        focusableElements[focusableElements.length - 1]!;
+      const activeElement: Element | null = document.activeElement;
+
+      if (!popup.contains(activeElement)) {
+        event.preventDefault();
+        (event.shiftKey ? lastElement : firstElement).focus();
+        return;
+      }
+
+      if (event.shiftKey && activeElement === firstElement) {
+        event.preventDefault();
+        lastElement.focus();
+        return;
+      }
+
+      if (!event.shiftKey && activeElement === lastElement) {
+        event.preventDefault();
+        firstElement.focus();
+      }
+    };
+
+    document.addEventListener("keydown", handleKeyDown, true);
+
+    return () => {
+      document.removeEventListener("keydown", handleKeyDown, true);
+    };
+  }, [isPopupOpen, closePopup]);
+
+  return {
+    anchorRef,
+    closePopup,
+    isPopupOpen,
+    popupPosition,
+    popupRef,
+    portalTarget: typeof document === "undefined" ? null : document.body,
+    togglePopup,
+  };
+};
+
+export default useAnchoredFieldPopup;

package/UI/Utils/Dropdown.ts

@@ -2,6 +2,7 @@ import NumberUtil from "../../Utils/Number";
 import { DropdownOption } from "../Components/Dropdown/Dropdown";
 import BaseModel from "../../Models/DatabaseModels/DatabaseBaseModel/DatabaseBaseModel";
 import Color from "../../Types/Color";
+import Text from "../../Types/Text";
 
 type Enum<E> = Record<keyof E, number | string> & { [k: number]: string };
 
@@ -31,6 +32,31 @@ export default class DropdownUtil {
     return dropdownOptions;
   }
 
+  /*
+   * Same as getDropdownOptionsFromEnum, but the LABEL is spaced out for
+   * reading: a value of "OnErrorOrFrustration" renders as "On Error Or
+   * Frustration". The stored value is untouched.
+   *
+   * Opt-in rather than the default behaviour of getDropdownOptionsFromEnum,
+   * because plenty of enums in this codebase carry values that must be
+   * shown verbatim - TechStack ("NodeJS"), CodeRepositoryType ("GitHub"),
+   * and the SSO SignatureMethod / DigestMethod identifiers, which are not
+   * prose at all. Reach for this when an enum's values are English words
+   * jammed together.
+   */
+  public static getDropdownOptionsFromEnumWithReadableLabels<T>(
+    obj: Enum<T>,
+  ): Array<DropdownOption> {
+    return DropdownUtil.getDropdownOptionsFromEnum(obj).map(
+      (option: DropdownOption): DropdownOption => {
+        return {
+          ...option,
+          label: Text.fromPascalCaseToReadable(option.label),
+        };
+      },
+    );
+  }
+
   public static getDropdownOptionFromEnumForValue<T>(
     enumObject: Enum<T>,
     value: string,

package/UI/Utils/DropdownAlignment.ts

@@ -0,0 +1,162 @@
+import React, { useEffect, useState } from "react";
+
+/*
+ * Horizontal edge of the trigger that a popup pins itself to.
+ * "Left" means the popup grows rightwards from the trigger's left edge
+ * (Tailwind `left-0`), "Right" means it grows leftwards from the trigger's
+ * right edge (Tailwind `right-0`).
+ */
+export enum DropdownHorizontalAlignment {
+  Left = "left",
+  Right = "right",
+}
+
+// Breathing room we keep between a popup and the edge of the viewport.
+export const DEFAULT_DROPDOWN_VIEWPORT_MARGIN_IN_PX: number = 8;
+
+export interface DropdownAlignmentInput {
+  // Viewport-relative left edge of the trigger, as reported by getBoundingClientRect().
+  anchorLeft: number;
+  // Viewport-relative right edge of the trigger.
+  anchorRight: number;
+  // Rendered width of the popup in pixels.
+  dropdownWidth: number;
+  // Width of the viewport in pixels.
+  viewportWidth: number;
+  // Optional override for the viewport gutter.
+  viewportMargin?: number | undefined;
+}
+
+/*
+ * Picks the edge a popup should align to so that it stays inside the viewport.
+ *
+ * Left alignment is preferred because it reads naturally next to the trigger.
+ * We only flip to the right edge when left alignment would spill past the right
+ * side of the viewport, and we never flip if doing so would spill past the left
+ * side by even more (which is what produced the off-screen popup on the metric
+ * explorer toolbar, where the trigger sits at the far left of the page).
+ */
+export function getDropdownHorizontalAlignment(
+  input: DropdownAlignmentInput,
+): DropdownHorizontalAlignment {
+  const margin: number =
+    input.viewportMargin === undefined
+      ? DEFAULT_DROPDOWN_VIEWPORT_MARGIN_IN_PX
+      : input.viewportMargin;
+
+  /*
+   * Before the popup is laid out (or in a non-visual environment) measurements
+   * come back as zero. There is nothing to solve for, so keep the default.
+   */
+  if (
+    !Number.isFinite(input.dropdownWidth) ||
+    !Number.isFinite(input.viewportWidth) ||
+    input.dropdownWidth <= 0 ||
+    input.viewportWidth <= 0
+  ) {
+    return DropdownHorizontalAlignment.Left;
+  }
+
+  // How far a left-aligned popup would poke past the right gutter.
+  const leftAlignedOverflow: number =
+    input.anchorLeft + input.dropdownWidth - (input.viewportWidth - margin);
+
+  // How far a right-aligned popup would poke past the left gutter.
+  const rightAlignedOverflow: number =
+    margin - (input.anchorRight - input.dropdownWidth);
+
+  if (leftAlignedOverflow <= 0) {
+    return DropdownHorizontalAlignment.Left;
+  }
+
+  if (rightAlignedOverflow <= 0) {
+    return DropdownHorizontalAlignment.Right;
+  }
+
+  // Neither edge fits. Pick whichever clips the least, preferring left on a tie.
+  return leftAlignedOverflow <= rightAlignedOverflow
+    ? DropdownHorizontalAlignment.Left
+    : DropdownHorizontalAlignment.Right;
+}
+
+/*
+ * Tailwind positioning class for an alignment. Kept next to the resolver so
+ * callers cannot drift out of sync with the enum.
+ */
+export function getDropdownAlignmentClassName(
+  alignment: DropdownHorizontalAlignment,
+): string {
+  return alignment === DropdownHorizontalAlignment.Right ? "right-0" : "left-0";
+}
+
+export interface UseDropdownHorizontalAlignmentOptions {
+  // Only measure while the popup is actually on screen.
+  isOpen: boolean;
+  // The trigger the popup hangs off.
+  anchorRef: React.RefObject<HTMLElement>;
+  // The popup itself. When it has not been laid out we fall back to the declared width.
+  dropdownRef?: React.RefObject<HTMLElement> | undefined;
+  // Width the popup is styled to (e.g. 288 for Tailwind `w-72`).
+  dropdownWidthInPx: number;
+  viewportMargin?: number | undefined;
+}
+
+/*
+ * Keeps a popup's horizontal alignment in sync with the space available around
+ * its trigger. Re-measures when the popup opens and whenever the viewport
+ * changes size or scrolls the trigger somewhere new.
+ */
+export function useDropdownHorizontalAlignment(
+  options: UseDropdownHorizontalAlignmentOptions,
+): DropdownHorizontalAlignment {
+  const [alignment, setAlignment] = useState<DropdownHorizontalAlignment>(
+    DropdownHorizontalAlignment.Left,
+  );
+
+  const {
+    isOpen,
+    anchorRef,
+    dropdownRef,
+    dropdownWidthInPx,
+    viewportMargin,
+  }: UseDropdownHorizontalAlignmentOptions = options;
+
+  useEffect(() => {
+    if (!isOpen) {
+      return undefined;
+    }
+
+    const measure: () => void = (): void => {
+      const anchor: HTMLElement | null = anchorRef.current;
+
+      if (!anchor || typeof anchor.getBoundingClientRect !== "function") {
+        return;
+      }
+
+      const anchorRect: DOMRect = anchor.getBoundingClientRect();
+      const measuredWidth: number = dropdownRef?.current?.offsetWidth || 0;
+
+      setAlignment(
+        getDropdownHorizontalAlignment({
+          anchorLeft: anchorRect.left,
+          anchorRight: anchorRect.right,
+          dropdownWidth: measuredWidth > 0 ? measuredWidth : dropdownWidthInPx,
+          viewportWidth: window.innerWidth,
+          viewportMargin: viewportMargin,
+        }),
+      );
+    };
+
+    measure();
+
+    window.addEventListener("resize", measure);
+    window.addEventListener("scroll", measure, true);
+
+    return () => {
+      window.removeEventListener("resize", measure);
+      window.removeEventListener("scroll", measure, true);
+    };
+  }, [isOpen, anchorRef, dropdownRef, dropdownWidthInPx, viewportMargin]);
+
+  return alignment;
+}

package/UI/Utils/TableFilterUrlState.ts

@@ -121,6 +121,59 @@ export default class TableFilterUrlState {
     });
   }
 
+  /**
+   * Serialize one slice exactly the way {@link write} puts it on the URL.
+   * Returns null for an empty slice (`null`, or an object with no keys) and for
+   * anything that will not serialize, so callers can treat "nothing to write"
+   * and "could not write" the same way.
+   */
+  public static serializeState(
+    state: JSONObject | null | undefined,
+  ): string | null {
+    if (!state || Object.keys(state).length === 0) {
+      return null;
+    }
+
+    try {
+      return JSON.stringify(JSONFunctions.serialize(state));
+    } catch (err) {
+      Logger.warn(`TableFilterUrlState: could not serialize state: ${err}`);
+      return null;
+    }
+  }
+
+  /**
+   * Query params that land a table already in a given filter/facet/view state,
+   * for *linking* to it from elsewhere in the product — a count on one page
+   * whose rows only exist on another.
+   *
+   * Values are percent-encoded here because {@link Route.addQueryParams}
+   * concatenates them into the route verbatim, while {@link read} pulls them
+   * back out through `URLSearchParams`, which decodes. Serialized facet state
+   * is JSON, so leaving it raw would produce a URL the reader cannot parse.
+   *
+   * Empty slices are omitted rather than written as an empty param — the
+   * absence of the param is what "no state" already means to {@link read}.
+   */
+  public static getLinkQueryParams(
+    tableId: string,
+    states: Partial<Record<TableFilterUrlStateKind, JSONObject | null>>,
+  ): Dictionary<string> {
+    const params: Dictionary<string> = {};
+
+    for (const kind of Object.keys(states) as Array<TableFilterUrlStateKind>) {
+      const value: string | null = this.serializeState(states[kind]);
+
+      if (value === null) {
+        continue;
+      }
+
+      params[this.getParamName(tableId, kind)] = encodeURIComponent(value);
+    }
+
+    return params;
+  }
+
   /*
    * Read a previously-persisted snapshot from the URL. Returns null when absent,
    * empty, or unparseable (e.g. a hand-edited param) so callers fall back to
@@ -195,26 +248,12 @@ export default class TableFilterUrlState {
       const state: JSONObject | null | undefined = states[kind];
       const paramName: string = this.getParamName(tableId, kind);
 
-      let value: string | null = null;
-
-      try {
-        const hasState: boolean = Boolean(
-          state && Object.keys(state).length > 0,
-        );
-
-        value = hasState
-          ? JSON.stringify(JSONFunctions.serialize(state as JSONObject))
-          : null;
-      } catch (err) {
-        /*
-         * Serialization failure (shouldn't happen for filter data) — drop the
-         * param rather than break the table, and leave a breadcrumb.
-         */
-        Logger.warn(
-          `TableFilterUrlState: could not serialize "${paramName}": ${err}`,
-        );
-        value = null;
-      }
+      /*
+       * A serialization failure (shouldn't happen for filter data) drops the
+       * param rather than breaking the table; serializeState leaves the
+       * breadcrumb.
+       */
+      let value: string | null = this.serializeState(state);
 
       if (value === null) {
         projected.delete(paramName);

package/UI/Utils/Timezone.ts

@@ -1,10 +1,26 @@
 import Timezone from "../../Types/Timezone";
 import { DropdownOption } from "../Components/Dropdown/Dropdown";
-import OneUptimeDate from "../../Types/Date";
+import OneUptimeDate, { Moment } from "../../Types/Date";
 
 export default class TimezoneUtil {
   public static getTimezoneDropdownOptions(): DropdownOption[] {
-    let timezoneOptions: Array<string> = Object.keys(Timezone);
+    /*
+     * The Timezone enum outlives the tzdb, so it can still list a zone the
+     * bundled moment-timezone has since dropped ("US/Pacific-New", removed in
+     * tzdata 2020b). Offering one is a trap: every consumer of the choice —
+     * the on-call rotation engine, the SLO windows, this user's own profile —
+     * then holds a zone that cannot be resolved to a wall clock. Filter them
+     * out at the source rather than leave each caller to discover it.
+     */
+    let timezoneOptions: Array<string> = Object.keys(Timezone).filter(
+      (key: string): boolean => {
+        const timezone: Timezone = Timezone[key as keyof typeof Timezone];
+
+        return (
+          Boolean(timezone) && Boolean(Moment.tz.zone(timezone.toString()))
+        );
+      },
+    );
 
     // order timezone by GMT offset.