Fix misaligned tooltip positions in modal dialogs

This commit fixes a bug that causes tooltips to be slightly misaligned.

Tooltip positioning was incorrect during modal transitions due to their
initial movement, causing tooltips to align incorrectly at the start of
the animation rather than the end.

One way to solve this would be using `autoUpdate` from `floating-ui`
with `animationFrame: true`. However, this recalculates positions tens
of times per second, impacting performance. This is a monkey solution.

This commit adopts a more efficient approach by updating tooltip
positions only at the end of the transitions, which reduces calculations
and conserves resources.

Key changes:

- Addd transition end event listener for updating tooltip positions.
- Use throttling to eliminate excessive position recalculations.

Other supporting changes:

- Improve throttle function to support efficient recalculations of
  positions:
  - Add ability to optionally exclude the first execution (leading
    call).
  - Refactor to simplify it make it easier to follow and read.
  - Fix a bug where initial calls were incorrectly throttled if
    `dateNow()` returned `0`.
- Introduce and use a global hook for efficient DOM event management.
  This greatily introduce safety, reuse and testability of event
  listening.

tests/unit/application/Common/Timing/Throttle.spec.ts

@@ -1,53 +1,116 @@
 import { describe, it, expect } from 'vitest';
 import { TimerStub } from '@tests/unit/shared/Stubs/TimerStub';
-import { throttle } from '@/application/Common/Timing/Throttle';
+import { throttle, type ThrottleOptions } from '@/application/Common/Timing/Throttle';
+import type { Timer } from '@/application/Common/Timing/Timer';
+import { formatAssertionMessage } from '@tests/shared/FormatAssertionMessage';
 
 describe('throttle', () => {
-  describe('validates parameters', () => {
-    describe('throws if waitInMs is invalid', () => {
-      // arrange
-      const testCases = [
+  describe('parameter validation', () => {
+    describe('throws for invalid waitInMs', () => {
+      const testCases: readonly {
+        readonly description: string;
+        readonly value: number;
+        readonly expectedError: string;
+      }[] = [
         {
-          name: 'given zero',
+          description: 'given zero',
           value: 0,
           expectedError: 'missing delay',
         },
         {
-          name: 'given negative',
+          description: 'given negative',
           value: -2,
           expectedError: 'negative delay',
         },
       ];
-      const noopCallback = () => { /* do nothing */ };
-      for (const testCase of testCases) {
-        it(`"${testCase.name}" throws "${testCase.expectedError}"`, () => {
+      testCases.forEach((
+        { description, expectedError, value: waitInMs },
+      ) => {
+        it(`"${description}" throws "${expectedError}"`, () => {
+          // arrange
+          const context = new TestContext()
+            .withWaitInMs(waitInMs);
           // act
-          const waitInMs = testCase.value;
-          const act = () => throttle(noopCallback, waitInMs);
+          const act = () => context.throttle();
           // assert
-          expect(act).to.throw(testCase.expectedError);
+          expect(act).to.throw(expectedError);
         });
-      }
+      });
     });
   });
-  it('should call the callback immediately', () => {
+  it('executes the leading callback immediately', () => {
     // arrange
     const timer = new TimerStub();
     let totalRuns = 0;
     const callback = () => totalRuns++;
-    const throttleFunc = throttle(callback, 500, timer);
+    const throttleFunc = new TestContext()
+      .withTimer(timer)
+      .withCallback(callback)
+      .throttle();
+
     // act
     throttleFunc();
+
     // assert
     expect(totalRuns).to.equal(1);
   });
-  it('should call the callback again after the timeout', () => {
+  it('executes the leading callback with initial arguments', () => {
+    // arrange
+    const expectedArguments = [1, 2, 3];
+    const timer = new TimerStub();
+    let lastArgs: readonly number[] | null = null;
+    const callback = (...args: readonly number[]) => { lastArgs = args; };
+    const waitInMs = 500;
+    const throttleFunc = new TestContext()
+      .withWaitInMs(waitInMs)
+      .withTimer(timer)
+      .withCallback(callback)
+      .throttle();
+
+    // act
+    throttleFunc(...expectedArguments);
+    timer.tickNext(waitInMs / 3);
+    throttleFunc(4, 5, 6);
+    timer.tickNext(waitInMs / 3);
+    throttleFunc(7, 8, 9);
+
+    // assert
+    expect(lastArgs).to.deep.equal(expectedArguments);
+  });
+  it('executes the trailing callback with final arguments', () => {
+    // arrange
+    const expectedArguments = [1, 2, 3];
+    const timer = new TimerStub();
+    let lastArgs: readonly number[] | null = null;
+    const callback = (...args: readonly number[]) => { lastArgs = args; };
+    const waitInMs = 500;
+    const throttleFunc = new TestContext()
+      .withWaitInMs(waitInMs)
+      .withTimer(timer)
+      .withCallback(callback)
+      .throttle();
+
+    // act
+    throttleFunc(1, 2, 3);
+    timer.tickNext(100);
+    throttleFunc(4, 5, 6);
+    timer.tickNext(100);
+    throttleFunc(lastArgs);
+
+    // assert
+    expect(lastArgs).to.deep.equal(expectedArguments);
+  });
+  it('executes the callback after the delay', () => {
     // arrange
     const timer = new TimerStub();
     let totalRuns = 0;
     const callback = () => totalRuns++;
     const waitInMs = 500;
-    const throttleFunc = throttle(callback, waitInMs, timer);
+    const throttleFunc = new TestContext()
+      .withWaitInMs(waitInMs)
+      .withTimer(timer)
+      .withCallback(callback)
+      .throttle();
     // act
     throttleFunc();
     totalRuns--; // So we don't count the initial run
@@ -56,53 +119,207 @@ describe('throttle', () => {
     // assert
     expect(totalRuns).to.equal(1);
   });
-  it('should call the callback at most once at given time', () => {
+  it('limits calls to at most once per period', () => {
     // arrange
+    const totalExpectedCalls = 2; // leading and trailing only
     const timer = new TimerStub();
     let totalRuns = 0;
     const callback = () => totalRuns++;
-    const waitInMs = 500;
+    const waitInMs = 200;
     const totalCalls = 10;
-    const throttleFunc = throttle(callback, waitInMs, timer);
+    const throttleFunc = new TestContext()
+      .withWaitInMs(waitInMs)
+      .withTimer(timer)
+      .withCallback(callback)
+      .throttle();
     // act
     for (let currentCall = 0; currentCall < totalCalls; currentCall++) {
       const currentTime = (waitInMs / totalCalls) * currentCall;
       timer.setCurrentTime(currentTime);
       throttleFunc();
     }
+    timer.tickNext(waitInMs);
     // assert
-    expect(totalRuns).to.equal(2); // one initial and one at the end
+    expect(totalRuns).to.equal(totalExpectedCalls);
   });
-  it('should call the callback as long as delay is waited', () => {
+  it('executes the callback after each complete delay period', () => {
     // arrange
     const timer = new TimerStub();
     let totalRuns = 0;
     const callback = () => totalRuns++;
     const waitInMs = 500;
     const expectedTotalRuns = 10;
-    const throttleFunc = throttle(callback, waitInMs, timer);
+    const throttleFunc = new TestContext()
+      .withWaitInMs(waitInMs)
+      .withTimer(timer)
+      .withCallback(callback)
+      .throttle();
     // act
-    for (let i = 0; i < expectedTotalRuns; i++) {
+    Array.from({ length: expectedTotalRuns }).forEach(() => {
       throttleFunc();
       timer.tickNext(waitInMs);
-    }
+    });
     // assert
     expect(totalRuns).to.equal(expectedTotalRuns);
   });
-  it('should call arguments as expected', () => {
-    // arrange
-    const timer = new TimerStub();
-    const expected = [1, 2, 3];
-    const actual = new Array<number>();
-    const callback = (arg: number) => { actual.push(arg); };
-    const waitInMs = 500;
-    const throttleFunc = throttle(callback, waitInMs, timer);
-    // act
-    for (const arg of expected) {
-      throttleFunc(arg);
+  describe('leading call exclusion', () => {
+    it('does not execute the callback immediately on the first call', () => {
+      // arrange
+      const timer = new TimerStub();
+      let totalRuns = 0;
+      const callback = () => totalRuns++;
+      const throttleFunc = new TestContext()
+        .withTimer(timer)
+        .withCallback(callback)
+        .withExcludeLeadingCall(true)
+        .throttle();
+      // act
+      throttleFunc();
+      // assert
+      expect(totalRuns).to.equal(0);
+    });
+    it('executes the initial call after the initial wait time', () => {
+      // arrange
+      const timer = new TimerStub();
+      let totalRuns = 0;
+      const waitInMs = 200;
+      const callback = () => totalRuns++;
+      const throttleFunc = new TestContext()
+        .withTimer(timer)
+        .withCallback(callback)
+        .withExcludeLeadingCall(true)
+        .withWaitInMs(waitInMs)
+        .throttle();
+      // act
+      throttleFunc();
       timer.tickNext(waitInMs);
-    }
-    // assert
-    expect(expected).to.deep.equal(actual);
+      // assert
+      expect(totalRuns).to.equal(1);
+    });
+    it('executes two calls after two wait periods', () => {
+      // arrange
+      const expectedTotalRuns = 2;
+      const calledArgs = new Array<string>();
+      const timer = new TimerStub();
+      const waitInMs = 300;
+      let totalRuns = 0;
+      const callback = (message: string) => {
+        totalRuns++;
+        calledArgs.push(message);
+      };
+      const throttleFunc = new TestContext()
+        .withTimer(timer)
+        .withCallback(callback)
+        .withWaitInMs(waitInMs)
+        .withExcludeLeadingCall(true)
+        .throttle();
+      // act
+      Array.from({ length: expectedTotalRuns }).forEach((_, index) => {
+        throttleFunc(`Call ${index} (zero-based, where initial call is 0)`);
+        timer.tickNext(waitInMs);
+      });
+      // assert
+      expect(totalRuns).to.equal(expectedTotalRuns, formatAssertionMessage([
+        `Expected total runs to equal ${expectedTotalRuns}, but got ${totalRuns}.`,
+        'Detailed call information:',
+        ...calledArgs.map((message, index) => `${index + 1}) ${message}`),
+      ]));
+    });
+    it('only executes once when multiple calls are made during the initial wait period', () => {
+      // arrange
+      const timer = new TimerStub();
+      let totalRuns = 0;
+      const callback = () => { totalRuns++; };
+      const waitInMs = 300;
+      const throttleFunc = new TestContext()
+        .withTimer(timer)
+        .withWaitInMs(waitInMs)
+        .withCallback(callback)
+        .withExcludeLeadingCall(true)
+        .throttle();
+      // act
+      throttleFunc();
+      timer.tickNext(waitInMs / 3);
+      throttleFunc();
+      timer.tickNext(waitInMs / 3);
+      throttleFunc();
+      timer.tickNext(waitInMs / 3);
+      // assert
+      expect(totalRuns).to.equal(1);
+    });
+    it('executes the last provided arguments only after the wait period expires', () => {
+      // arrange
+      const expectedLastArg = 'trailing call';
+      const timer = new TimerStub();
+      let actualLastArg: string | null = null;
+      const callback = (arg: string) => {
+        actualLastArg = arg;
+      };
+      const waitInMs = 300;
+      const throttleFunc = new TestContext()
+        .withTimer(timer)
+        .withWaitInMs(waitInMs)
+        .withCallback(callback)
+        .withExcludeLeadingCall(true)
+        .throttle();
+      // act
+      throttleFunc('leading call');
+      timer.tickNext(waitInMs / 3);
+      throttleFunc('call in the middle');
+      timer.tickNext(waitInMs / 3);
+      throttleFunc(expectedLastArg);
+      timer.tickNext(waitInMs / 3);
+      // assert
+      expect(actualLastArg).to.equal(expectedLastArg);
+    });
   });
 });
+
+type CallbackType = Parameters<typeof throttle>[0];
+
+class TestContext {
+  private options: Partial<ThrottleOptions> | undefined = {
+    timer: new TimerStub(),
+  };
+
+  private waitInMs: number = 500;
+
+  private callback: CallbackType = () => { /* NO OP */ };
+
+  public withTimer(timer: Timer): this {
+    return this.withOptions({
+      ...(this.options ?? {}),
+      timer,
+    });
+  }
+
+  public withWaitInMs(waitInMs: number): this {
+    this.waitInMs = waitInMs;
+    return this;
+  }
+
+  public withCallback(callback: CallbackType): this {
+    this.callback = callback;
+    return this;
+  }
+
+  public withExcludeLeadingCall(excludeLeadingCall: boolean): this {
+    return this.withOptions({
+      ...(this.options ?? {}),
+      excludeLeadingCall,
+    });
+  }
+
+  public withOptions(options: Partial<ThrottleOptions> | undefined): this {
+    this.options = options;
+    return this;
+  }
+
+  public throttle(): ReturnType<typeof throttle> {
+    return throttle(
+      this.callback,
+      this.waitInMs,
+      this.options,
+    );
+  }
+}