From b41be0a80439bebe0a8e58eab8d2fd93952ed82d Mon Sep 17 00:00:00 2001
From: Jeff Daley <jeffdaley@users.noreply.github.com>
Date: Thu, 6 Jul 2023 15:58:20 -0400
Subject: [PATCH] Cleanup and documentation

---
 web/app/modifiers/tooltip.ts                  | 61 +++++++++++--------
 .../integration/modifiers/tooltip-test.ts     |  2 +-
 2 files changed, 35 insertions(+), 28 deletions(-)

diff --git a/web/app/modifiers/tooltip.ts b/web/app/modifiers/tooltip.ts
index e4a321f80..f9595b1b6 100644
--- a/web/app/modifiers/tooltip.ts
+++ b/web/app/modifiers/tooltip.ts
@@ -19,11 +19,16 @@ import { guidFor } from "@ember/object/internals";
 import htmlElement from "hermes/utils/html-element";
 import { restartableTask, timeout } from "ember-concurrency";
 import Ember from "ember";
-import { set } from "mockdate";
 import simpleTimeout from "hermes/utils/simple-timeout";
 
 const DEFAULT_DELAY = Ember.testing ? 0 : 275;
 
+enum TooltipState {
+  Opening = "opening",
+  Open = "open",
+  Closed = "closed",
+}
+
 /**
  * A modifier that attaches a tooltip to a reference element on hover or focus.
  *
@@ -32,8 +37,8 @@ const DEFAULT_DELAY = Ember.testing ? 0 : 275;
  *  <FlightIcon @name="arrow-left" />
  * </div>
  *
- * Takes text and an optional named `placement` argument:
- * {{tooltip "Go back" placement="left-end"}}
+ * Takes text and optional arguments:
+ * {{tooltip "Go back" placement="left-end" delay=0}}
  *
  * TODO:
  * - Add `renderInPlace` argument
@@ -47,7 +52,7 @@ interface TooltipModifierSignature {
     Named: {
       placement?: Placement;
       delay?: number;
-      _isTestingDelay?: boolean;
+      _useTestDelay?: boolean;
     };
   };
 }
@@ -80,12 +85,6 @@ function cleanup(instance: TooltipModifier) {
   }
 }
 
-enum TooltipState {
-  Opening = "opening",
-  Open = "open",
-  Closed = "closed",
-}
-
 export default class TooltipModifier extends Modifier<TooltipModifierSignature> {
   constructor(owner: any, args: ArgsFor<TooltipModifierSignature>) {
     super(owner, args);
@@ -133,9 +132,24 @@ export default class TooltipModifier extends Modifier<TooltipModifierSignature>
    */
   @tracked placement: Placement = "top";
 
+  /**
+   * The delay before the tooltip is shown.
+   * Can be overridden with a `delay` argument.
+   */
   @tracked delay: number = DEFAULT_DELAY;
-  @tracked _isTestingDelay: boolean = false;
 
+  /**
+   * Whether to use a delay in the testing environment.
+   * Triggers a short `simpleTimeout` on open so we can test
+   * the content's intermediary states.
+   */
+  @tracked _useTestDelay: boolean = false;
+
+  /**
+   * Whether the content should stay open on click.
+   * Used in components like `CopyURLButton` where we want to show
+   * a "success" message without closing and reopening the tooltip.
+   */
   @tracked stayOpenOnClick = false;
 
   /**
@@ -162,20 +176,13 @@ export default class TooltipModifier extends Modifier<TooltipModifierSignature>
     return this._arrow;
   }
 
-  get isOpening() {
-    return this.state === TooltipState.Opening;
-  }
-
-  get isOpen() {
-    return this.state === TooltipState.Open;
-  }
-
-  get isClosed() {
-    return this.state === TooltipState.Closed;
-  }
-
   @tracked floatingUICleanup: (() => void) | null = null;
 
+  /**
+   * The action that runs when the content's [visibility] state changes.
+   * Updates the `data-tooltip-state` attribute on the reference
+   * so we can test intermediary states.
+   */
   @action updateState(state: TooltipState) {
     this.state = state;
     if (this.reference) {
@@ -204,7 +211,7 @@ export default class TooltipModifier extends Modifier<TooltipModifierSignature>
       await timeout(this.delay);
     }
 
-    if (this._isTestingDelay) {
+    if (this._useTestDelay) {
       await simpleTimeout(10);
     }
 
@@ -404,7 +411,7 @@ export default class TooltipModifier extends Modifier<TooltipModifierSignature>
       placement?: Placement;
       stayOpenOnClick?: boolean;
       delay?: number;
-      _isTestingDelay?: boolean;
+      _useTestDelay?: boolean;
     }
   ) {
     this._reference = element;
@@ -420,8 +427,8 @@ export default class TooltipModifier extends Modifier<TooltipModifierSignature>
       this.stayOpenOnClick = named.stayOpenOnClick;
     }
 
-    if (named._isTestingDelay) {
-      this._isTestingDelay = named._isTestingDelay;
+    if (named._useTestDelay) {
+      this._useTestDelay = named._useTestDelay;
     }
 
     if (named.delay !== undefined) {
diff --git a/web/tests/integration/modifiers/tooltip-test.ts b/web/tests/integration/modifiers/tooltip-test.ts
index deab65940..dd18574f3 100644
--- a/web/tests/integration/modifiers/tooltip-test.ts
+++ b/web/tests/integration/modifiers/tooltip-test.ts
@@ -116,7 +116,7 @@ module("Integration | Modifier | tooltip", function (hooks) {
 
   test("it can open on a delay", async function (assert) {
     await render(hbs`
-      <div class="tip" {{tooltip "more information" _isTestingDelay=true}}>
+      <div class="tip" {{tooltip "more information" _useTestDelay=true}}>
         Hover or focus me
       </div>
     `);