Fix code highlighting and optimize category select

This commit introduces a batched debounce mechanism for managing user
selection state changes. It effectively reduces unnecessary processing
during rapid script checking, preventing multiple triggers for code
compilation and UI rendering.

Key improvements include:

- Enhanced performance, especially noticeable when selecting large
  categories. This update resolves minor UI freezes experienced when
  selecting categories with numerous scripts.
- Correction of a bug where the code area only highlighted the last
  selected script when multiple scripts were chosen.

Other changes include:

- Timing functions:
  - Create a `Timing` folder for `throttle` and the new
    `batchedDebounce` functions.
  - Move these functions to the application layer from the presentation
    layer, reflecting their application-wide use.
  - Refactor existing code for improved clarity, naming consistency, and
    adherence to new naming conventions.
  - Add missing unit tests.
- `UserSelection`:
  - State modifications in `UserSelection` now utilize a singular object
    inspired by the CQRS pattern, enabling batch updates and flexible
    change configurations, thereby simplifying change management.
- Remove the `I` prefix from related interfaces to align with new coding
  standards.
- Refactor related code for better testability in isolation with
  dependency injection.
- Repository:
  - Move repository abstractions to the application layer.
  - Improve repository abstraction to combine `ReadonlyRepository` and
    `MutableRepository` interfaces.
- E2E testing:
  - Introduce E2E tests to validate the correct batch selection
    behavior.
  - Add a specialized data attribute in `TheCodeArea.vue` for improved
    testability.
  - Reorganize shared Cypress functions for a more idiomatic Cypress
    approach.
  - Improve test documentation with related information.
- `SelectedScript`:
  - Create an abstraction for simplified testability.
  - Introduce `SelectedScriptStub` in tests as a substitute for the
    actual object.

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

@@ -0,0 +1,144 @@
+import { describe, it, expect } from 'vitest';
+import { batchedDebounce } from '@/application/Common/Timing/BatchedDebounce';
+import { TimerStub } from '@tests/unit/shared/Stubs/TimerStub';
+
+describe('batchedDebounce', () => {
+  describe('immediate invocation', () => {
+    it('does not call the the callback immediately on the first call', () => {
+      // arrange
+      const { calledBatches, callback } = createObservableCallback();
+      const callArg = 'first';
+      const debounceFunc = batchedDebounce(callback, 100, new TimerStub());
+
+      // act
+      debounceFunc(callArg);
+
+      // assert
+      expect(calledBatches).to.have.lengthOf(0);
+    });
+  });
+
+  describe('debounce timing', () => {
+    it('executes the callback after the debounce period', () => {
+      // arrange
+      const { calledBatches, callback } = createObservableCallback();
+      const expectedArg = 'first';
+      const debouncePeriodInMs = 100;
+      const timer = new TimerStub();
+      const debounceFunc = batchedDebounce(callback, debouncePeriodInMs, timer);
+
+      // act
+      debounceFunc(expectedArg);
+      timer.tickNext(debouncePeriodInMs);
+
+      // assert
+      expect(calledBatches).to.have.lengthOf(1);
+      expect(calledBatches).to.deep.include([expectedArg]);
+    });
+    it('prevents callback invocation within the debounce period', () => {
+      // arrange
+      const { calledBatches, callback } = createObservableCallback();
+      const debouncePeriodInMs = 100;
+      const timer = new TimerStub();
+      const debounceFunc = batchedDebounce(callback, debouncePeriodInMs, timer);
+
+      // act
+      debounceFunc('first');
+      timer.tickNext(debouncePeriodInMs / 4);
+      debounceFunc('second');
+      timer.tickNext(debouncePeriodInMs / 4);
+      debounceFunc('third');
+      timer.tickNext(debouncePeriodInMs / 4);
+
+      // assert
+      expect(calledBatches).to.have.lengthOf(0);
+    });
+    it('resets debounce timer on subsequent calls', () => {
+      // arrange
+      const timer = new TimerStub();
+      const { calledBatches, callback } = createObservableCallback();
+      const debouncePeriodInMs = 100;
+      const debounceFunc = batchedDebounce(callback, debouncePeriodInMs, timer);
+
+      // act
+      debounceFunc('first');
+      timer.tickNext(debouncePeriodInMs * 0.9);
+      debounceFunc('second');
+      timer.tickNext(debouncePeriodInMs * 0.9);
+      debounceFunc('third');
+      timer.tickNext(debouncePeriodInMs * 0.9);
+
+      // assert
+      expect(calledBatches).to.have.lengthOf(0);
+    });
+    it('does not call the callback again if no new calls are made after the debounce period', () => {
+      // arrange
+      const { calledBatches, callback } = createObservableCallback();
+      const debouncePeriodInMs = 100;
+      const timer = new TimerStub();
+      const debounceFunc = batchedDebounce(callback, debouncePeriodInMs, timer);
+
+      // act
+      debounceFunc('first');
+      timer.tickNext(debouncePeriodInMs);
+      timer.tickNext(debouncePeriodInMs);
+      timer.tickNext(debouncePeriodInMs);
+      timer.tickNext(debouncePeriodInMs);
+
+      // assert
+      expect(calledBatches).to.have.lengthOf(1);
+    });
+  });
+
+  describe('batching calls', () => {
+    it('batches multiple calls within the debounce period', () => {
+      // arrange
+      const { calledBatches, callback } = createObservableCallback();
+      const firstCallArg = 'first';
+      const secondCallArg = 'second';
+      const debouncePeriodInMs = 100;
+      const timer = new TimerStub();
+      const debounceFunc = batchedDebounce(callback, debouncePeriodInMs, timer);
+
+      // act
+      debounceFunc(firstCallArg);
+      debounceFunc(secondCallArg);
+      timer.tickNext(debouncePeriodInMs);
+
+      // assert
+      expect(calledBatches).to.have.lengthOf(1);
+      expect(calledBatches).to.deep.include([firstCallArg, secondCallArg]);
+    });
+    it('handles multiple separate batches correctly', () => {
+      // arrange
+      const { calledBatches, callback } = createObservableCallback();
+      const debouncePeriodInMs = 100;
+      const firstBatchArg = 'first';
+      const secondBatchArg = 'second';
+      const timer = new TimerStub();
+      const debounceFunc = batchedDebounce(callback, debouncePeriodInMs, timer);
+
+      // act
+      debounceFunc(firstBatchArg);
+      timer.tickNext(debouncePeriodInMs);
+      debounceFunc(secondBatchArg);
+      timer.tickNext(debouncePeriodInMs);
+
+      // assert
+      expect(calledBatches).to.have.lengthOf(2);
+      expect(calledBatches[0]).to.deep.equal([firstBatchArg]);
+      expect(calledBatches[1]).to.deep.equal([secondBatchArg]);
+    });
+  });
+});
+
+function createObservableCallback() {
+  const calledBatches = new Array<readonly string[]>();
+  const callback = (batches: readonly string[]): void => {
+    calledBatches.push(batches);
+  };
+  return {
+    calledBatches,
+    callback,
+  };
+}

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

@@ -0,0 +1,78 @@
+import {
+  describe, it, expect, beforeEach,
+  afterEach,
+} from 'vitest';
+import { PlatformTimer } from '@/application/Common/Timing/PlatformTimer';
+
+describe('PlatformTimer', () => {
+  let originalSetTimeout: typeof global.setTimeout;
+  let originalClearTimeout: typeof global.clearTimeout;
+  let originalDateNow: typeof global.Date.now;
+
+  beforeEach(() => {
+    originalSetTimeout = global.setTimeout;
+    originalClearTimeout = global.clearTimeout;
+    originalDateNow = Date.now;
+    Date.now = () => originalDateNow();
+  });
+
+  afterEach(() => {
+    global.setTimeout = originalSetTimeout;
+    global.clearTimeout = originalClearTimeout;
+    Date.now = originalDateNow;
+  });
+
+  describe('setTimeout', () => {
+    it('calls the global setTimeout with the provided delay', () => {
+      // arrange
+      const expectedDelay = 55;
+      let actualDelay: number | undefined;
+      global.setTimeout = ((_, delay) => {
+        actualDelay = delay;
+      }) as typeof global.setTimeout;
+      // act
+      PlatformTimer.setTimeout(() => { /* NOOP */ }, expectedDelay);
+      // assert
+      expect(actualDelay).to.equal(expectedDelay);
+    });
+    it('calls the global setTimeout with the provided callback', () => {
+      // arrange
+      const expectedCallback = () => { /* NOOP */ };
+      let actualCallback: typeof expectedCallback | undefined;
+      global.setTimeout = ((callback) => {
+        actualCallback = callback;
+      }) as typeof global.setTimeout;
+      // act
+      PlatformTimer.setTimeout(expectedCallback, 33);
+      // assert
+      expect(actualCallback).to.equal(expectedCallback);
+    });
+  });
+
+  describe('clearTimeout', () => {
+    it('should clear timeout', () => {
+      // arrange
+      let actualTimer: ReturnType<typeof PlatformTimer.setTimeout> | undefined;
+      global.clearTimeout = ((timer) => {
+        actualTimer = timer;
+      }) as typeof global.clearTimeout;
+      const expectedTimer = PlatformTimer.setTimeout(() => { /* NOOP */ }, 1);
+      // act
+      PlatformTimer.clearTimeout(expectedTimer);
+      // assert
+      expect(actualTimer).to.equal(expectedTimer);
+    });
+  });
+
+  describe('dateNow', () => {
+    it('should get current date', () => {
+      // arrange
+      const expected = Date.now();
+      Date.now = () => expected;
+      // act
+      const actual = PlatformTimer.dateNow();
+      // assert
+      expect(expected).to.equal(actual);
+    });
+  });
+});

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

@@ -0,0 +1,108 @@
+import { describe, it, expect } from 'vitest';
+import { TimerStub } from '@tests/unit/shared/Stubs/TimerStub';
+import { throttle } from '@/application/Common/Timing/Throttle';
+
+describe('throttle', () => {
+  describe('validates parameters', () => {
+    describe('throws if waitInMs is invalid', () => {
+      // arrange
+      const testCases = [
+        {
+          name: 'given zero',
+          value: 0,
+          expectedError: 'missing delay',
+        },
+        {
+          name: 'given negative',
+          value: -2,
+          expectedError: 'negative delay',
+        },
+      ];
+      const noopCallback = () => { /* do nothing */ };
+      for (const testCase of testCases) {
+        it(`"${testCase.name}" throws "${testCase.expectedError}"`, () => {
+          // act
+          const waitInMs = testCase.value;
+          const act = () => throttle(noopCallback, waitInMs);
+          // assert
+          expect(act).to.throw(testCase.expectedError);
+        });
+      }
+    });
+  });
+  it('should call the callback immediately', () => {
+    // arrange
+    const timer = new TimerStub();
+    let totalRuns = 0;
+    const callback = () => totalRuns++;
+    const throttleFunc = throttle(callback, 500, timer);
+    // act
+    throttleFunc();
+    // assert
+    expect(totalRuns).to.equal(1);
+  });
+  it('should call the callback again after the timeout', () => {
+    // arrange
+    const timer = new TimerStub();
+    let totalRuns = 0;
+    const callback = () => totalRuns++;
+    const waitInMs = 500;
+    const throttleFunc = throttle(callback, waitInMs, timer);
+    // act
+    throttleFunc();
+    totalRuns--; // So we don't count the initial run
+    throttleFunc();
+    timer.tickNext(waitInMs);
+    // assert
+    expect(totalRuns).to.equal(1);
+  });
+  it('should call the callback at most once at given time', () => {
+    // arrange
+    const timer = new TimerStub();
+    let totalRuns = 0;
+    const callback = () => totalRuns++;
+    const waitInMs = 500;
+    const totalCalls = 10;
+    const throttleFunc = throttle(callback, waitInMs, timer);
+    // act
+    for (let currentCall = 0; currentCall < totalCalls; currentCall++) {
+      const currentTime = (waitInMs / totalCalls) * currentCall;
+      timer.setCurrentTime(currentTime);
+      throttleFunc();
+    }
+    // assert
+    expect(totalRuns).to.equal(2); // one initial and one at the end
+  });
+  it('should call the callback as long as delay is waited', () => {
+    // arrange
+    const timer = new TimerStub();
+    let totalRuns = 0;
+    const callback = () => totalRuns++;
+    const waitInMs = 500;
+    const expectedTotalRuns = 10;
+    const throttleFunc = throttle(callback, waitInMs, timer);
+    // act
+    for (let i = 0; i < expectedTotalRuns; i++) {
+      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);
+      timer.tickNext(waitInMs);
+    }
+    // assert
+    expect(expected).to.deep.equal(actual);
+  });
+});