@oneuptime/common 14.0.2 → 14.0.3

package/UI/Components/ModelTable/BaseModelTable.tsx

@@ -208,6 +208,19 @@ export interface BulkActionProps<T extends BaseModel | AnalyticsBaseModel> {
    * cannot be undone - it cannot know what else goes with it.
    */
   deleteConfirmationWarning?: string | undefined;
+  /**
+   * The word the default bulk Delete uses instead of "Delete", for a table
+   * whose rows are relationships rather than things - "Unlink" on a table of
+   * links, say. When set, the menu item, the confirmation's title and its
+   * sentence all use it ("Unlink 3 Alerts", "Are you sure you want to unlink
+   * 3 alerts?"), and the sentence no longer claims the action cannot be
+   * undone: removing a relationship is undone by adding it again. It is still
+   * the table's delete action - it deletes the selected rows, is gated on the
+   * model's delete permission, and stops a second Delete being added.
+   */
+  deleteVerb?: string | undefined;
+  /* The menu icon to go with deleteVerb. Defaults to the trash can. */
+  deleteIcon?: IconProp | undefined;
 }
 
 /**
@@ -562,6 +575,29 @@ const BaseModelTable: <TBaseModel extends BaseModel | AnalyticsBaseModel>(
 
   const model: TBaseModel = new props.modelType();
 
+  /*
+   * The header's create button, "<verb> <noun>". Translating the two words
+   * separately reads the verb out of context - "Link" comes back as the noun
+   * in many languages, and word order differs - so the whole phrase is looked
+   * up first ("Link Alert") and the word-by-word join is only the fallback
+   * for a phrase with no entry of its own. In English both are the same.
+   */
+  const getCreateButtonTitle: () => string = (): string => {
+    const verb: string = props.createVerb || "Create";
+    const noun: string = props.singularName || model.singularName || "";
+
+    if (noun) {
+      const phrase: string = `${verb} ${noun}`;
+      const translatedPhrase: string = tx(phrase);
+
+      if (translatedPhrase && translatedPhrase !== phrase) {
+        return translatedPhrase;
+      }
+    }
+
+    return `${tx(verb)} ${tx(noun)}`;
+  };
+
   /*
    * How a create / update / delete affordance should be rendered for this
    * viewer. A user without the permission used to simply not see the button,
@@ -586,8 +622,18 @@ const BaseModelTable: <TBaseModel extends BaseModel | AnalyticsBaseModel>(
   const getActionGate: GetActionGateFunction = (
     action: ModelAction,
   ): ActionGate => {
+    /*
+     * A table that calls its delete "Unlink" must not say the locked button
+     * would delete the row's noun ("permission to delete this Alert"). Keyed
+     * on deleteVerb alone: deleteButtonText is also set by tables such as
+     * "Remove from Project", which keep the default "delete" sentence.
+     */
     const result: PermissionGateResult = PermissionGate.check(model, action, {
       singularName: props.singularName || model.singularName || undefined,
+      verb:
+        action === ModelAction.Delete
+          ? props.bulkActions?.deleteVerb?.trim() || undefined
+          : undefined,
     });
 
     if (result.isAllowed) {
@@ -2446,9 +2492,7 @@ const BaseModelTable: <TBaseModel extends BaseModel | AnalyticsBaseModel>(
       showAs !== ShowAs.OrderedStatesList
     ) {
       headerbuttons.push({
-        title: `${tx(props.createVerb || "Create")} ${tx(
-          props.singularName || model.singularName || "",
-        )}`,
+        title: getCreateButtonTitle(),
         buttonStyle: ButtonStyleType.NORMAL,
         buttonSize: ButtonSize.Normal,
         className: "",
@@ -2908,10 +2952,16 @@ const BaseModelTable: <TBaseModel extends BaseModel | AnalyticsBaseModel>(
 
       const deleteGate: ActionGate = getActionGate(ModelAction.Delete);
 
+      /* The row action wears the same icon as the bulk one it stands for. */
+      const rowDeleteIcon: IconProp =
+        (props.bulkActions?.deleteVerb?.trim() &&
+          props.bulkActions?.deleteIcon) ||
+        IconProp.Trash;
+
       if (props.isDeleteable && deleteGate.show) {
         actionsSchema.push({
           title: tx(props.deleteButtonText || "Delete"),
-          icon: IconProp.Trash,
+          icon: rowDeleteIcon,
           buttonStyleType: ButtonStyleType.DANGER_OUTLINE,
           disabled: deleteGate.disabled,
           tooltip: deleteGate.tooltip,
@@ -3008,28 +3058,43 @@ const BaseModelTable: <TBaseModel extends BaseModel | AnalyticsBaseModel>(
 
   const getDeleteBulkAction: GetDeleteBulkActionFunction =
     (): BulkActionButtonSchema<TBaseModel> => {
+      /*
+       * A table that names its own verb ("Unlink") removes relationships, not
+       * things, so its sentence drops "This action cannot be undone" - that
+       * would say the opposite of the warning it usually appends.
+       */
+      const deleteVerb: string | undefined =
+        props.bulkActions?.deleteVerb?.trim() || undefined;
+
+      type GetItemLabelFunction = (items: Array<TBaseModel>) => string;
+
+      const getItemLabel: GetItemLabelFunction = (
+        items: Array<TBaseModel>,
+      ): string => {
+        return items.length === 1
+          ? props.singularName || model.singularName || "item"
+          : props.pluralName || model.pluralName || "items";
+      };
+
       return {
-        title: "Delete",
+        title: deleteVerb || "Delete",
         buttonStyleType: ButtonStyleType.DANGER,
-        icon: IconProp.Trash,
+        icon: (deleteVerb && props.bulkActions?.deleteIcon) || IconProp.Trash,
         confirmMessage: (items: Array<TBaseModel>) => {
-          const itemLabel: string =
-            items.length === 1
-              ? props.singularName || model.singularName || "item"
-              : props.pluralName || model.pluralName || "items";
+          const itemLabel: string = getItemLabel(items);
 
           const warning: string = props.bulkActions?.deleteConfirmationWarning
             ? ` ${props.bulkActions.deleteConfirmationWarning}`
             : "";
 
+          if (deleteVerb) {
+            return `Are you sure you want to ${deleteVerb.toLowerCase()} ${items.length} ${itemLabel.toLowerCase()}?${warning}`;
+          }
+
           return `Are you sure you want to delete ${items.length} ${itemLabel}? This action cannot be undone.${warning}`;
         },
         confirmTitle: (items: Array<TBaseModel>) => {
-          const itemLabel: string =
-            items.length === 1
-              ? props.singularName || model.singularName || "item"
-              : props.pluralName || model.pluralName || "items";
-          return `Delete ${items.length} ${itemLabel}`;
+          return `${deleteVerb || "Delete"} ${items.length} ${getItemLabel(items)}`;
         },
         confirmButtonStyleType: ButtonStyleType.DANGER,
         onClick: async ({
@@ -3207,7 +3272,19 @@ const BaseModelTable: <TBaseModel extends BaseModel | AnalyticsBaseModel>(
            * Table derives the row checkboxes from this array being non-empty,
            * so injecting a locked Delete into an otherwise empty array would
            * grow a selection column onto tables that have never had one.
+           *
+           * A page's own button counts as the delete action when it carries
+           * the title the default one would have: "Delete", or the table's
+           * deleteVerb.
            */
+          const deleteActionTitles: Array<string> = ["Delete"];
+          const bulkDeleteVerb: string | undefined =
+            props.bulkActions?.deleteVerb?.trim() || undefined;
+
+          if (bulkDeleteVerb) {
+            deleteActionTitles.push(bulkDeleteVerb);
+          }
+
           const alreadyHasDeleteAction: boolean = sourceButtons.some(
             (
               action:
@@ -3221,8 +3298,9 @@ const BaseModelTable: <TBaseModel extends BaseModel | AnalyticsBaseModel>(
                 typeof action === "object" &&
                 action !== null &&
                 "title" in action &&
-                (action as BulkActionButtonSchema<TBaseModel>).title ===
-                  "Delete"
+                deleteActionTitles.includes(
+                  (action as BulkActionButtonSchema<TBaseModel>).title,
+                )
               ) {
                 return true;
               }

package/UI/Components/ModelTable/Column.ts

@@ -63,6 +63,11 @@ export default interface Columns<
   colSpan?: number | undefined;
   disableSort?: boolean;
   description?: string | undefined;
+  /*
+   * What the column's values mean, in an (i) beside the header (see the
+   * Table Column of the same name). Spread through to the table as is.
+   */
+  headerTooltip?: string | undefined;
   type: FieldType;
   tooltipText?: ((item: TEntity) => string) | undefined;
   actionButtons?: Array<ActionButton>;

package/UI/Components/Table/TableHeader.tsx

@@ -10,6 +10,7 @@ import { VoidFunction } from "../../../Types/FunctionTypes";
 import GenericObject from "../../../Types/GenericObject";
 import IconProp from "../../../Types/Icon/IconProp";
 import useTranslateValue from "../../Utils/Translation";
+import InfoTooltip from "../Tooltip/InfoTooltip";
 import React, { ReactElement, useEffect, useState } from "react";
 
 export interface ComponentProps<T extends GenericObject> {
@@ -157,10 +158,21 @@ const TableHeader: TableHeaderFunction = <T extends GenericObject>(
               </>
             );
 
+            /*
+             * A header's name is computed from its content, and the (i)
+             * button's "About <title>" would join it - every cell in the
+             * column would be announced as "Last seen About Last seen". The
+             * column is named by its title alone; the (i) keeps its own name.
+             */
+            const headerLabel: string | undefined = column.headerTooltip?.trim()
+              ? translateString(column.title) ?? column.title
+              : undefined;
+
             return (
               <th
                 key={i}
                 scope="col"
+                aria-label={headerLabel}
                 aria-sort={ariaSort}
                 className="text-left text-sm font-semibold text-gray-900"
               >
@@ -172,7 +184,27 @@ const TableHeader: TableHeaderFunction = <T extends GenericObject>(
                  * padding moves onto the button so the clickable area is the
                  * whole cell, exactly as before.
                  */}
-                {canSort ? (
+                {/*
+                 * A header tooltip is its own button, and a button may not
+                 * sit inside the sort button - so for those columns the sort
+                 * button shrinks to its content and the (i) follows it.
+                 */}
+                {canSort && column.headerTooltip?.trim() ? (
+                  <div className="flex w-full items-center">
+                    <button
+                      type="button"
+                      onClick={sortColumn}
+                      className="flex py-3 pl-6 pr-1 cursor-pointer text-left font-semibold text-gray-900 focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-indigo-500"
+                    >
+                      {headerContent}
+                    </button>
+                    <InfoTooltip
+                      label={translateString(column.title) ?? column.title}
+                      text={column.headerTooltip}
+                      className="mr-6 font-normal"
+                    />
+                  </div>
+                ) : canSort ? (
                   <button
                     type="button"
                     onClick={sortColumn}
@@ -181,7 +213,20 @@ const TableHeader: TableHeaderFunction = <T extends GenericObject>(
                     {headerContent}
                   </button>
                 ) : (
-                  <div className={contentClassName}>{headerContent}</div>
+                  <div
+                    className={
+                      column.headerTooltip?.trim()
+                        ? `${contentClassName} items-center`
+                        : contentClassName
+                    }
+                  >
+                    {headerContent}
+                    <InfoTooltip
+                      label={translateString(column.title) ?? column.title}
+                      text={column.headerTooltip}
+                      className="ml-1 font-normal"
+                    />
+                  </div>
                 )}
               </th>
             );

package/UI/Components/Table/Types/Column.ts

@@ -8,6 +8,13 @@ export default interface Column<T extends GenericObject> {
   // Stable identity carried over from the ModelTable column, if it had one.
   id?: string | undefined;
   description?: string | undefined;
+  /*
+   * What the column's values mean, in an (i) tooltip beside the header - for
+   * a metric column whose title is jargon ("p95", "Restarts"). Separate from
+   * `description`, which ModelTable fills from the database column for other
+   * purposes and which is never shown in the header.
+   */
+  headerTooltip?: string | undefined;
   disableSort?: boolean | undefined;
   tooltipText?: ((item: T) => string) | undefined;
   type: FieldType;

package/UI/Components/Tooltip/InfoTooltip.tsx

@@ -0,0 +1,78 @@
+import React, { FunctionComponent, ReactElement } from "react";
+import IconProp from "../../../Types/Icon/IconProp";
+import Icon from "../Icon/Icon";
+import Tooltip from "./Tooltip";
+
+/*
+ * A small (i) beside a label that explains it on hover or keyboard focus -
+ * "what does p95 mean?" answered where the number is, rather than in the
+ * docs. Built for metric tiles and chart headers, but nothing here is
+ * metric-specific.
+ *
+ * The trigger is a real <button> so it is reachable with Tab and announced
+ * as a control; Tippy shows the text on focus as well as on hover and links
+ * it with aria-describedby. It is lazy: an overview page draws dozens of
+ * these, and none of them needs a Tippy instance until someone reaches for
+ * it.
+ *
+ * A click is swallowed, and so are Enter and Space: the (i) can sit inside a
+ * card that is itself a link or a button, and asking what a number means
+ * should not navigate away from it.
+ */
+
+export interface ComponentProps {
+  // The explanation. Nothing renders when it is empty.
+  text?: string | undefined;
+  /*
+   * What is being explained, e.g. the metric's title. Names the button for
+   * screen readers ("About p95 duration") and is never shown.
+   */
+  label: string;
+  className?: string | undefined;
+  iconClassName?: string | undefined;
+  dataTestId?: string | undefined;
+}
+
+const InfoTooltip: FunctionComponent<ComponentProps> = (
+  props: ComponentProps,
+): ReactElement => {
+  const text: string = (props.text || "").trim();
+
+  if (!text) {
+    return <></>;
+  }
+
+  return (
+    <Tooltip text={text} lazy={true}>
+      <button
+        type="button"
+        aria-label={`About ${props.label}`}
+        data-testid={props.dataTestId}
+        className={`inline-flex flex-shrink-0 items-center justify-center rounded-full text-gray-400 hover:text-gray-600 focus:outline-none focus-visible:text-gray-600 focus-visible:ring-2 focus-visible:ring-indigo-500 focus-visible:ring-offset-1 ${
+          props.className || ""
+        }`}
+        onClick={(event: React.MouseEvent<HTMLButtonElement>): void => {
+          event.preventDefault();
+          event.stopPropagation();
+        }}
+        /*
+         * A clickable card that handles Enter / Space itself (InfoCard, a
+         * tile acting as a button) would otherwise hear these keys bubble up
+         * from the (i) and activate.
+         */
+        onKeyDown={(event: React.KeyboardEvent<HTMLButtonElement>): void => {
+          if (event.key === "Enter" || event.key === " ") {
+            event.stopPropagation();
+          }
+        }}
+      >
+        <Icon
+          icon={IconProp.InformationCircle}
+          className={props.iconClassName || "h-3.5 w-3.5"}
+        />
+      </button>
+    </Tooltip>
+  );
+};
+
+export default InfoTooltip;

package/UI/Utils/PermissionGate.ts

@@ -79,6 +79,13 @@ export interface PermissionGateOptions {
    * what the user sees on screen ("Monitor" vs "Monitor Template").
    */
   singularName?: string | undefined;
+  /*
+   * The verb to use in the message when the operation is presented as
+   * something other than its own name - a table of links whose delete action
+   * is labelled "Unlink", say. Only the wording changes: the permissions
+   * checked and listed are still the ones for `action`.
+   */
+  verb?: string | undefined;
 }
 
 /*
@@ -176,15 +183,17 @@ export default class PermissionGate {
     const singularName: string =
       options?.singularName || model.singularName || "item";
 
+    const verb: string = (options?.verb?.trim() || action).toLowerCase();
+
     const titles: Array<string> = this.getPermissionTitles(
       this.getModelPermissions(model, action),
     );
 
     if (titles.length === 0) {
-      return `You do not have permission to ${action} this ${singularName}.`;
+      return `You do not have permission to ${verb} this ${singularName}.`;
     }
 
-    return `You do not have permission to ${action} this ${singularName}. You need one of these permissions: ${titles.join(
+    return `You do not have permission to ${verb} this ${singularName}. You need one of these permissions: ${titles.join(
       ", ",
     )}.`;
   }