@oneuptime/common 14.0.13 → 14.0.14

package/UI/Components/ModelSwitch/ModelSwitchesCard.tsx

@@ -0,0 +1,265 @@
+import BaseModel from "../../../Models/DatabaseModels/DatabaseBaseModel/DatabaseBaseModel";
+import Select from "../../../Types/BaseDatabase/Select";
+import ObjectID from "../../../Types/ObjectID";
+import API from "../../Utils/API/API";
+import ModelAPI from "../../Utils/ModelAPI/ModelAPI";
+import Card from "../Card/Card";
+import ComponentLoader from "../ComponentLoader/ComponentLoader";
+import ErrorMessage from "../ErrorMessage/ErrorMessage";
+import ModelSwitchRow, { ModelSwitchConfirmation } from "./ModelSwitchRow";
+import {
+  getColumnBooleanDefault,
+  isModelSwitchOn,
+  ModelSwitchColumn,
+} from "./ModelSwitchUtil";
+import React, {
+  MutableRefObject,
+  ReactElement,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+
+/*
+ * A card of switches for one record: the card's title and the line under
+ * it, then one row per yes-or-no setting, each its own boolean column and
+ * each saving the moment it is flipped (ModelSwitchRow). It is what a card
+ * becomes whose Edit dialog held nothing but switches - "Investigate new
+ * incidents", "Draft a postmortem when an incident resolves" - so that
+ * every one of them took Edit, flip, Save, and a wizard when there were
+ * enough of them.
+ *
+ * ModelSwitchCard is the one-switch card; this is its twin for a list. Both
+ * read the record the same way:
+ *
+ * - once, for every switch's column (and any `select` the page wants
+ *   alongside them, handed to onLoaded), showing a loader while it reads
+ *   and why a read failed, with a way to try again;
+ * - a column the record never had set reads as its model's default.
+ *
+ * Each row keeps its own state from there: it saves only its own column,
+ * locks for someone who may not change that column (its own update
+ * permissions, as well as the record's), names the plan it needs, asks
+ * first where the page says so, moves back with the server's reason when a
+ * save is refused, and follows a save of its column made anywhere else on
+ * the screen (ModelSwitchEvents).
+ */
+
+export interface ModelSwitchesCardSwitch<TBaseModel extends BaseModel> {
+  column: ModelSwitchColumn<TBaseModel>;
+  // The switch's name and its sentences, in English, as on ModelSwitchRow.
+  title: string;
+  getDescription?: ((isOn: boolean) => string | undefined) | undefined;
+  note?: string | undefined;
+  isInverted?: boolean | undefined;
+  getConfirmation?:
+    | ((isTurningOn: boolean) => ModelSwitchConfirmation | undefined)
+    | undefined;
+  /*
+   * The switch's data-testid. Its row is `${dataTestId}-row` and its
+   * "Saved" status `${dataTestId}-status`.
+   */
+  dataTestId: string;
+}
+
+export interface ComponentProps<TBaseModel extends BaseModel> {
+  modelType: { new (): TBaseModel };
+  modelId: ObjectID;
+  // The card's title and the line under it, in English.
+  cardTitle: string;
+  cardDescription?: string | ReactElement | undefined;
+  // The switches, in the order they are drawn.
+  switches: Array<ModelSwitchesCardSwitch<TBaseModel>>;
+  // ModelAPI when left out; the admin dashboard passes AdminModelAPI.
+  modelAPI?: typeof ModelAPI | undefined;
+  // More columns to read along with the switches', for onLoaded.
+  select?: Select<TBaseModel> | undefined;
+  // Told what was read, each time the record is read.
+  onLoaded?: ((item: TBaseModel) => void) | undefined;
+  /*
+   * Told whether a switch is on: once the record is read (for every
+   * switch), whenever one moves, and again if a change is refused and it
+   * moves back.
+   */
+  onChange?:
+    | ((column: ModelSwitchColumn<TBaseModel>, isOn: boolean) => void)
+    | undefined;
+  // Told after a change is saved, with the switch and whether it is now on.
+  onSaved?:
+    | ((column: ModelSwitchColumn<TBaseModel>, isOn: boolean) => void)
+    | undefined;
+  // The card body's data-testid.
+  dataTestId: string;
+}
+
+// Where each switch is when the record is read, by column.
+type SwitchPositions = Record<string, boolean>;
+
+const ModelSwitchesCard: <TBaseModel extends BaseModel>(
+  props: ComponentProps<TBaseModel>,
+) => ReactElement = <TBaseModel extends BaseModel>(
+  props: ComponentProps<TBaseModel>,
+): ReactElement => {
+  const [positions, setPositions] = useState<SwitchPositions | null>(null);
+  const [isLoading, setIsLoading] = useState<boolean>(true);
+  const [error, setError] = useState<string>("");
+
+  /*
+   * Bumped by every read: an answer for a read the card has moved on from
+   * (another record, a retry) is dropped.
+   */
+  const readRef: MutableRefObject<number> = useRef<number>(0);
+
+  const modelIdString: string = props.modelId.toString();
+
+  // The columns, as one string, so a new array of the same switches is no change.
+  const columnsKey: string = props.switches
+    .map((definition: ModelSwitchesCardSwitch<TBaseModel>): string => {
+      return definition.column;
+    })
+    .join(",");
+
+  const fetchItem: () => Promise<void> = async (): Promise<void> => {
+    const read: number = readRef.current + 1;
+    readRef.current = read;
+
+    setIsLoading(true);
+    setError("");
+
+    const modelAPI: typeof ModelAPI = props.modelAPI || ModelAPI;
+
+    const select: Record<string, unknown> = {
+      ...((props.select || {}) as Record<string, unknown>),
+    };
+
+    for (const definition of props.switches) {
+      select[definition.column] = true;
+    }
+
+    try {
+      const item: TBaseModel | null = await modelAPI.getItem<TBaseModel>({
+        modelType: props.modelType,
+        id: props.modelId,
+        select: select as Select<TBaseModel>,
+      });
+
+      if (read !== readRef.current) {
+        return;
+      }
+
+      if (!item) {
+        setPositions(null);
+        setError("Item not found");
+      } else {
+        const model: TBaseModel = new props.modelType();
+        const readPositions: SwitchPositions = {};
+
+        for (const definition of props.switches) {
+          readPositions[definition.column] = isModelSwitchOn({
+            stored: (item as unknown as Record<string, unknown>)[
+              definition.column
+            ],
+            defaultValue: getColumnBooleanDefault(model, definition.column),
+            isInverted: definition.isInverted,
+          });
+        }
+
+        setPositions(readPositions);
+        props.onLoaded?.(item);
+
+        for (const definition of props.switches) {
+          props.onChange?.(
+            definition.column,
+            Boolean(readPositions[definition.column]),
+          );
+        }
+      }
+    } catch (err) {
+      if (read !== readRef.current) {
+        return;
+      }
+
+      setPositions(null);
+      setError(API.getFriendlyMessage(err));
+    }
+
+    setIsLoading(false);
+  };
+
+  useEffect(() => {
+    void fetchItem();
+
+    return () => {
+      readRef.current += 1;
+    };
+  }, [modelIdString, columnsKey]);
+
+  const getBody: () => ReactElement = (): ReactElement => {
+    if (isLoading) {
+      return <ComponentLoader />;
+    }
+
+    if (error || !positions) {
+      return (
+        <ErrorMessage
+          message={error || "Item not found"}
+          onRefreshClick={() => {
+            void fetchItem();
+          }}
+        />
+      );
+    }
+
+    return (
+      /*
+       * Full-bleed rows, ruled like the card's own header rule, as on the
+       * project's Notification Channels card and the status page's "What
+       * your status page shows".
+       */
+      <div className="-mx-5 -mb-6 divide-y divide-gray-200 border-t border-gray-200 md:-mx-6">
+        {props.switches.map(
+          (definition: ModelSwitchesCardSwitch<TBaseModel>): ReactElement => {
+            return (
+              <div
+                className="px-5 py-4 md:px-6"
+                /*
+                 * Keyed on the record too, so a switch read for one record
+                 * never shows on the next one's card.
+                 */
+                key={`${modelIdString}-${definition.column}`}
+              >
+                <ModelSwitchRow<TBaseModel>
+                  modelType={props.modelType}
+                  modelId={props.modelId}
+                  column={definition.column}
+                  initialValue={Boolean(positions[definition.column])}
+                  title={definition.title}
+                  getDescription={definition.getDescription}
+                  note={definition.note}
+                  isInverted={definition.isInverted}
+                  getConfirmation={definition.getConfirmation}
+                  modelAPI={props.modelAPI}
+                  onChange={(isOn: boolean): void => {
+                    props.onChange?.(definition.column, isOn);
+                  }}
+                  onSaved={(isOn: boolean): void => {
+                    props.onSaved?.(definition.column, isOn);
+                  }}
+                  dataTestId={definition.dataTestId}
+                />
+              </div>
+            );
+          },
+        )}
+      </div>
+    );
+  };
+
+  return (
+    <Card title={props.cardTitle} description={props.cardDescription}>
+      <div data-testid={props.dataTestId}>{getBody()}</div>
+    </Card>
+  );
+};
+
+export default ModelSwitchesCard;

package/UI/Components/ModelSwitch/useSaveModelSwitch.ts

@@ -0,0 +1,144 @@
+import BaseModel from "../../../Models/DatabaseModels/DatabaseBaseModel/DatabaseBaseModel";
+import { JSONObject } from "../../../Types/JSON";
+import ObjectID from "../../../Types/ObjectID";
+import API from "../../Utils/API/API";
+import ModelAPI from "../../Utils/ModelAPI/ModelAPI";
+import PermissionGate, {
+  PermissionGateResult,
+} from "../../Utils/PermissionGate";
+import { announceModelSwitchSaved } from "./ModelSwitchEvents";
+import { ModelSwitchColumn } from "./ModelSwitchUtil";
+import {
+  MutableRefObject,
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+
+/*
+ * A button that sets a switch's column from somewhere other than the switch:
+ * "Turn evaluation on" on the banner that says an SLO is not being
+ * evaluated, with the switch itself on the SLO's Settings page. It writes
+ * what the switch writes, gated the way the switch is
+ * (PermissionGate.checkColumnUpdate), and announces the save through
+ * ModelSwitchEvents, so the switch - and anything else on the screen that
+ * listens - moves with it.
+ *
+ * Someone who could not flip the switch gets a locked button that says
+ * which permission is missing, not a save the server refuses.
+ *
+ * What it is doing, and why a press failed, belong to the record it was
+ * pressed for: a page stays mounted when the reader follows a link to
+ * another record of the same kind, and that one's button must not show the
+ * first one's error or spinner.
+ */
+
+export interface SaveModelSwitch {
+  // Whether the button can be pressed, and if not, why.
+  gate: PermissionGateResult;
+  isSaving: boolean;
+  // Why the last press did not save, or "".
+  error: string;
+  save: () => void;
+}
+
+interface ForRecord {
+  modelId: string;
+  message: string;
+}
+
+const useSaveModelSwitch: <TBaseModel extends BaseModel>(data: {
+  modelType: { new (): TBaseModel };
+  modelId: ObjectID;
+  column: ModelSwitchColumn<TBaseModel>;
+  // What the column is set to: the stored value, not what a switch shows.
+  value: boolean;
+  // Told after it is saved.
+  onSaved?: (() => void) | undefined;
+  // ModelAPI when left out; the admin dashboard passes AdminModelAPI.
+  modelAPI?: typeof ModelAPI | undefined;
+}) => SaveModelSwitch = <TBaseModel extends BaseModel>(data: {
+  modelType: { new (): TBaseModel };
+  modelId: ObjectID;
+  column: ModelSwitchColumn<TBaseModel>;
+  value: boolean;
+  onSaved?: (() => void) | undefined;
+  modelAPI?: typeof ModelAPI | undefined;
+}): SaveModelSwitch => {
+  // The record a save is out for, if any.
+  const [savingFor, setSavingFor] = useState<string | null>(null);
+  const [failure, setFailure] = useState<ForRecord | null>(null);
+
+  // Set at once: two presses before the button locks must not save twice.
+  const isSavingRef: MutableRefObject<boolean> = useRef<boolean>(false);
+
+  // The latest call's options, for a save that outlives a render.
+  const latestRef: MutableRefObject<typeof data> = useRef<typeof data>(data);
+  latestRef.current = data;
+
+  const modelIdString: string = data.modelId.toString();
+
+  const model: TBaseModel = useMemo((): TBaseModel => {
+    return new data.modelType();
+  }, [data.modelType]);
+
+  const gate: PermissionGateResult = PermissionGate.checkColumnUpdate(
+    model,
+    data.column,
+  );
+
+  const save: () => void = useCallback((): void => {
+    if (isSavingRef.current || !gate.isAllowed) {
+      return;
+    }
+
+    isSavingRef.current = true;
+    setSavingFor(modelIdString);
+    setFailure(null);
+
+    const current: typeof data = latestRef.current;
+    const modelId: ObjectID = new ObjectID(modelIdString);
+    const modelAPI: typeof ModelAPI = current.modelAPI || ModelAPI;
+
+    const run: () => Promise<void> = async (): Promise<void> => {
+      try {
+        await modelAPI.updateById<TBaseModel>({
+          modelType: current.modelType,
+          id: modelId,
+          data: {
+            [current.column]: current.value,
+          } as JSONObject,
+        });
+
+        announceModelSwitchSaved({
+          modelType: current.modelType,
+          modelId: modelId,
+          column: current.column,
+          value: current.value,
+        });
+
+        current.onSaved?.();
+      } catch (err) {
+        setFailure({
+          modelId: modelIdString,
+          message: API.getFriendlyMessage(err),
+        });
+      }
+
+      isSavingRef.current = false;
+      setSavingFor(null);
+    };
+
+    void run();
+  }, [modelIdString, gate.isAllowed]);
+
+  return {
+    gate,
+    isSaving: savingFor === modelIdString,
+    error: failure?.modelId === modelIdString ? failure.message : "",
+    save,
+  };
+};
+
+export default useSaveModelSwitch;

package/UI/Components/ModelTable/BaseModelTable.tsx

@@ -226,6 +226,11 @@ export interface BaseTableCallbacks<
     onBeforeCreate?: ModelFormOnBeforeCreate<TBaseModel> | undefined;
     onSuccess?: ((item: TBaseModel) => void) | undefined;
     onClose?: (() => void) | undefined;
+    /*
+     * The rows the table shows, handed to a Create form: a colour it picks
+     * for the new record is one none of them uses yet.
+     */
+    existingItems?: Array<TBaseModel> | undefined;
   }) => ReactElement;
 }
 
@@ -5233,6 +5238,7 @@ const BaseModelTable: <TBaseModel extends BaseModel | AnalyticsBaseModel>(
             modalType === ModalType.Edit && currentEditableItem
               ? new ObjectID(currentEditableItem["_id"] as string)
               : undefined,
+          existingItems: modalType === ModalType.Create ? data : undefined,
         })
       ) : (
         <></>

package/UI/Components/ModelTable/ModelTable.tsx

@@ -293,6 +293,7 @@ const ModelTable: <TBaseModel extends BaseModel>(
             onBeforeCreate?: ModelFormOnBeforeCreate<TBaseModel> | undefined;
             onSuccess?: ((item: TBaseModel) => void) | undefined;
             onClose?: (() => void) | undefined;
+            existingItems?: Array<TBaseModel> | undefined;
           }): ReactElement => {
             const {
               modalType,
@@ -300,6 +301,7 @@ const ModelTable: <TBaseModel extends BaseModel>(
               onBeforeCreate,
               onSuccess,
               onClose,
+              existingItems,
             } = data;
 
             return (
@@ -375,6 +377,9 @@ const ModelTable: <TBaseModel extends BaseModel>(
                     modalType === ModalType.Create
                       ? FormType.Create
                       : FormType.Update,
+                  // A colour picked for a new row is one no row uses yet.
+                  existingItems:
+                    modalType === ModalType.Create ? existingItems : undefined,
                 }}
                 modelIdToEdit={modelIdToEdit}
               />

package/UI/Components/Navbar/NavBar.tsx

@@ -53,14 +53,15 @@ export interface ComponentProps {
   rightElement?: NavItem;
   moreMenuItems?: MoreMenuItem[];
   /*
-   * The categories the products menu opens on. Every other category starts
-   * folded to one line (its name, how many products it holds and what they
-   * are called) until the user opens it; search still finds every product,
-   * and the category holding the current page opens by itself. Leave it
-   * unset to show every category open: a short menu has nothing to fold.
-   * See NavBarMenuCatalog.ts.
+   * The categories the products menu always shows open: it opens on them,
+   * and they never fold, whatever the browser remembers. Every other
+   * category starts folded to one line (its name, how many products it holds
+   * and what they are called) until the user opens it; search still finds
+   * every product, and the category holding the current page opens by
+   * itself. Leave it unset to show every category open: a short menu has
+   * nothing to fold. See NavBarMenuCatalog.ts.
    */
-  moreMenuCategoriesOpenByDefault?: Array<string> | undefined;
+  moreMenuCategoriesAlwaysOpen?: Array<string> | undefined;
   moreMenuTitle?: string; // Title for the more menu (default: "Products")
   moreMenuSearchPlaceholder?: string; // Placeholder for the menu search box
   moreMenuNoResultsText?: string; // Empty-state text when search matches nothing
@@ -375,7 +376,7 @@ const Navbar: FunctionComponent<ComponentProps> = (
               <NavBarMobileMenu
                 items={props.items}
                 moreMenuItems={props.moreMenuItems || []}
-                categoriesOpenByDefault={props.moreMenuCategoriesOpenByDefault}
+                categoriesAlwaysOpen={props.moreMenuCategoriesAlwaysOpen}
                 rightElement={props.rightElement}
                 onNavigate={() => {
                   return setIsMobileMenuOpen(false);
@@ -539,7 +540,7 @@ const Navbar: FunctionComponent<ComponentProps> = (
         createPortal(
           <NavBarMenuModal
             items={props.moreMenuItems}
-            categoriesOpenByDefault={props.moreMenuCategoriesOpenByDefault}
+            categoriesAlwaysOpen={props.moreMenuCategoriesAlwaysOpen}
             footer={props.moreMenuFooter}
             searchPlaceholder={props.moreMenuSearchPlaceholder}
             noResultsText={props.moreMenuNoResultsText}

package/UI/Components/Navbar/NavBarMenuCatalog.ts

@@ -5,7 +5,7 @@ import { useState } from "react";
 
 /*
  * The products menu's catalog rules: which product is the page the user is
- * on, how products group into categories, and which categories start folded.
+ * on, how products group into categories, and which categories fold.
  *
  * Kept out of the components so the desktop products menu (NavBarMenuModal)
  * and the phone menu (NavBar) answer these questions the same way, and so the
@@ -66,7 +66,7 @@ export function groupItemsByCategory(
 }
 
 /*
- * Which categories start folded.
+ * Which categories fold.
  *
  * The maintainer asked to "reduce decision / choice paralysis as much as
  * possible: show people as few options as possible". The Dashboard's products
@@ -74,21 +74,28 @@ export function groupItemsByCategory(
  * two-line description, so someone looking for Incidents read past
  * Kubernetes, Proxmox and Ceph to find it.
  *
- * So a menu that names the categories it opens on (the Dashboard names
- * Essentials) folds every other category down to one line: its name, how
- * many products it holds and what they are called. One click, or Enter,
+ * So a menu that names the categories it always shows open (the Dashboard
+ * names Essentials) folds every other category down to one line: its name,
+ * how many products it holds and what they are called. One click, or Enter,
  * opens it. Nothing is removed: search ignores folding and finds every
  * product, and the category holding the page the user is on opens by itself,
  * so the menu always shows where they are.
  *
- * What someone opens or folds is remembered on their browser, so a team that
- * lives in Infrastructure does not open it again on every visit. A menu that
- * names no categories (the Admin Dashboard's six entries) shows every
- * category open, as before.
+ * The categories a menu names never fold. The maintainer asked to "always
+ * have Essentials expanded by default": they are the products a problem
+ * flows through, and the reason most people open the menu. So they sit under
+ * a plain heading, like Recent, with no chevron to fold them away, and no
+ * remembered choice hides them, not even a fold remembered from before this
+ * rule, when Essentials could still be folded.
+ *
+ * What someone opens or folds in the other categories is remembered on their
+ * browser, so a team that lives in Infrastructure does not open it again on
+ * every visit. A menu that names no categories (the Admin Dashboard's six
+ * entries) shows every category open, as before.
  */
 export interface CategoryFoldState {
-  // The categories the menu opens on. Every other one starts folded.
-  openByDefault: ReadonlyArray<string>;
+  // The categories that are always open. Every other one starts folded.
+  alwaysOpen: ReadonlyArray<string>;
   // The categories holding the page the user is on.
   holdingCurrentPage: ReadonlyArray<string>;
   // What this person opened or folded before, on this browser.
@@ -97,15 +104,28 @@ export interface CategoryFoldState {
   chosenNow: ReadonlyMap<string, boolean>;
 }
 
+// Whether a category folds at all: the ones that are always open never do.
+export function canCategoryFold(
+  category: string,
+  state: CategoryFoldState,
+): boolean {
+  return !state.alwaysOpen.includes(category);
+}
+
 /*
- * A choice made in this menu wins; then the page the user is on, which must
- * never be folded away when the menu opens; then what they chose last time;
- * then the menu's default.
+ * A category that is always open is open, whatever else. For every other
+ * one, a choice made in this menu wins; then the page the user is on, which
+ * must never be folded away when the menu opens; then what they chose last
+ * time; otherwise it is folded.
  */
 export function isCategoryOpen(
   category: string,
   state: CategoryFoldState,
 ): boolean {
+  if (!canCategoryFold(category, state)) {
+    return true;
+  }
+
   const chosenNow: boolean | undefined = state.chosenNow.get(category);
 
   if (chosenNow !== undefined) {
@@ -122,7 +142,7 @@ export function isCategoryOpen(
     return remembered;
   }
 
-  return state.openByDefault.includes(category);
+  return false;
 }
 
 /*
@@ -187,10 +207,19 @@ export function rememberCategoryFold(category: string, isOpen: boolean): void {
 }
 
 export interface CategoryFolds {
-  // False for a menu that names no categories to open on: nothing folds.
+  // False for a menu that names no categories to keep open: nothing folds.
   isEnabled: boolean;
+  /*
+   * Whether the category folds at all, so it gets a fold control. The
+   * categories the menu keeps open never do; nor does any category of a menu
+   * that folds nothing.
+   */
+  canFold: (category: string) => boolean;
   isOpen: (category: string) => boolean;
-  // Open a folded category, or fold an open one, and remember it.
+  /*
+   * Open a folded category, or fold an open one, and remember it. A category
+   * that cannot fold is left as it is, and nothing is remembered for it.
+   */
   toggle: (category: string) => void;
 }
 
@@ -201,9 +230,9 @@ export interface CategoryFolds {
  */
 export function useCategoryFolds(
   items: ReadonlyArray<MoreMenuItem>,
-  categoriesOpenByDefault: ReadonlyArray<string> | undefined,
+  categoriesAlwaysOpen: ReadonlyArray<string> | undefined,
 ): CategoryFolds {
-  const isEnabled: boolean = Boolean(categoriesOpenByDefault);
+  const isEnabled: boolean = Boolean(categoriesAlwaysOpen);
 
   const [remembered] = useState<Map<string, boolean>>(() => {
     return isEnabled ? readRememberedCategoryFolds() : new Map();
@@ -220,18 +249,24 @@ export function useCategoryFolds(
     .map(categoryOf);
 
   const state: CategoryFoldState = {
-    openByDefault: categoriesOpenByDefault || [],
+    alwaysOpen: categoriesAlwaysOpen || [],
     holdingCurrentPage,
     remembered,
     chosenNow,
   };
 
+  const canFold: (category: string) => boolean = (
+    category: string,
+  ): boolean => {
+    return isEnabled && canCategoryFold(category, state);
+  };
+
   const isOpen: (category: string) => boolean = (category: string): boolean => {
     return !isEnabled || isCategoryOpen(category, state);
   };
 
   const toggle: (category: string) => void = (category: string): void => {
-    if (!isEnabled) {
+    if (!canFold(category)) {
       return;
     }
 
@@ -246,5 +281,5 @@ export function useCategoryFolds(
     rememberCategoryFold(category, nextIsOpen);
   };
 
-  return { isEnabled, isOpen, toggle };
+  return { isEnabled, canFold, isOpen, toggle };
 }