feat: event cue (#473)

* feat: parse cue

* refactor: get delay from backend

* feat: add cue to UI

* refactor: remove deprecated delay logic

* refactor: extract studio clock specific logic

* refactor: extract utilities

* refactor: fix issue with missing key

* style: prevent cue overflow

* style: prevent whitespace wrap

* feat: add support for cues in integrations

packages/utils/src/cue-utils/cueUtils.test.ts

@@ -0,0 +1,160 @@
+import { OntimeRundown, SupportedEvent } from 'ontime-types';
+
+import { getCueCandidate, getIncrement, sanitiseCue } from './cueUtils.js';
+
+describe('getIncrement()', () => {
+  it('increments number', () => {
+    expect(getIncrement('1')).toBe('2');
+    expect(getIncrement('10')).toBe('11');
+    expect(getIncrement('99')).toBe('100');
+    expect(getIncrement('101')).toBe('102');
+  });
+  it('increments decimal number', () => {
+    expect(getIncrement('1.1')).toBe('1.2');
+    expect(getIncrement('10.10')).toBe('10.11');
+    expect(getIncrement('99.99')).toBe('99.100');
+    expect(getIncrement('101.101')).toBe('101.102');
+    // NOTE: we know the below would fail, handling this amount of decimals is outside of scope
+    // expect(getIncrement('101.999')).toBe('101.1000');
+  });
+  // NOTE: we also know the following fails since we only handle one decimal
+  //it('handles multiple decimals', () => {
+  //  expect(getIncrement('2.1.1')).toBe('2.1.2');
+  //});
+  it('finds last digit in string', () => {
+    expect(getIncrement('Presenter1')).toBe('Presenter2');
+    expect(getIncrement('Presenter10')).toBe('Presenter11');
+    expect(getIncrement('Presenter99')).toBe('Presenter100');
+    expect(getIncrement('Presenter101')).toBe('Presenter102');
+  });
+  it('adds a 2 if none is found', () => {
+    expect(getIncrement('Presenter')).toBe('Presenter2');
+  });
+});
+
+describe('findCueName()', () => {
+  describe('in the beginning of the rundown', () => {
+    it('names cue as 1 if next event does not collide', () => {
+      const testRundown = [
+        { id: '1', cue: '10', type: SupportedEvent.Event },
+        { id: '2', cue: '11', type: SupportedEvent.Event },
+      ] as OntimeRundown;
+      const cue = getCueCandidate(testRundown);
+      expect(cue).toBe('1');
+    });
+    it('creates decimal stem if next cue is 1', () => {
+      const testRundown = [
+        { id: '1', cue: '1', type: SupportedEvent.Event },
+        { id: '2', cue: '10', type: SupportedEvent.Event },
+      ] as OntimeRundown;
+      const cue = getCueCandidate(testRundown);
+      expect(cue).toBe('0.1');
+    });
+  });
+  describe('in the middle of the rundown', () => {
+    it('names cue as an increment if next event has different stem (case of numbers)', () => {
+      const testRundown = [
+        { id: '1', cue: '1', type: SupportedEvent.Event },
+        { id: '2', cue: '10', type: SupportedEvent.Event },
+      ] as OntimeRundown;
+      const cue = getCueCandidate(testRundown, '1');
+      expect(cue).toBe('2');
+    });
+    it('names cue as an increment if next event has different stem (case of letters)', () => {
+      const testRundown = [
+        { id: '1', cue: 'Presenter', type: SupportedEvent.Event },
+        {
+          id: '2',
+          cue: 'Interval',
+          type: SupportedEvent.Event,
+        },
+      ] as OntimeRundown;
+      const cue = getCueCandidate(testRundown, '1');
+      expect(cue).toBe('Presenter2');
+    });
+    it('creates decimal stem if next cue has same stem (case of numbers)', () => {
+      const testRundown = [
+        { id: '1', cue: '1', type: SupportedEvent.Event },
+        { id: '2', cue: '2', type: SupportedEvent.Event },
+      ] as OntimeRundown;
+      const cue = getCueCandidate(testRundown, '1');
+      expect(cue).toBe('1.1');
+    });
+    it('creates decimal stem if next cue has same stem (case of letters)', () => {
+      const testRundown = [
+        { id: '1', cue: 'Presenter1', type: SupportedEvent.Event },
+        { id: '2', cue: 'Presenter2', type: SupportedEvent.Event },
+      ] as OntimeRundown;
+      const cue = getCueCandidate(testRundown, '1');
+      expect(cue).toBe('Presenter1.1');
+    });
+  });
+});
+
+describe('findCueName() with mixed events', () => {
+  describe('in the beginning of the rundown', () => {
+    it('names cue as 1 if next event does not collide', () => {
+      const testRundown = [
+        { id: '1', cue: '10', type: SupportedEvent.Event },
+        { id: '2', cue: '11', type: SupportedEvent.Event },
+      ] as OntimeRundown;
+      const cue = getCueCandidate(testRundown);
+      expect(cue).toBe('1');
+    });
+    it('creates decimal stem if next cue is 1', () => {
+      const testRundown = [
+        { id: '1', cue: '1', type: SupportedEvent.Event },
+        { id: '2', cue: '10', type: SupportedEvent.Event },
+      ] as OntimeRundown;
+      const cue = getCueCandidate(testRundown);
+      expect(cue).toBe('0.1');
+    });
+  });
+  describe('in the middle of the rundown', () => {
+    it('names cue as an increment if next event has different stem (case of numbers)', () => {
+      const testRundown = [
+        { id: '1', cue: '1', type: SupportedEvent.Event },
+        { id: '2', cue: '10', type: SupportedEvent.Event },
+      ] as OntimeRundown;
+      const cue = getCueCandidate(testRundown, '1');
+      expect(cue).toBe('2');
+    });
+    it('names cue as an increment if next event has different stem (case of letters)', () => {
+      const testRundown = [
+        { id: '1', cue: 'Presenter', type: SupportedEvent.Event },
+        { id: '2', cue: 'Interval', type: SupportedEvent.Event },
+      ] as OntimeRundown;
+      const cue = getCueCandidate(testRundown, '1');
+      expect(cue).toBe('Presenter2');
+    });
+    it('creates decimal stem if next cue has same stem (case of numbers)', () => {
+      const testRundown = [
+        { id: '1', cue: '1', type: SupportedEvent.Event },
+        { id: '2', cue: '2', type: SupportedEvent.Event },
+      ] as OntimeRundown;
+      const cue = getCueCandidate(testRundown, '1');
+      expect(cue).toBe('1.1');
+    });
+    it('creates decimal stem if next cue has same stem (case of letters)', () => {
+      const testRundown = [
+        { id: '1', cue: 'Presenter1', type: SupportedEvent.Event },
+        { id: '2', cue: 'Presenter2', type: SupportedEvent.Event },
+      ] as OntimeRundown;
+      const cue = getCueCandidate(testRundown, '1');
+      expect(cue).toBe('Presenter1.1');
+    });
+  });
+});
+
+describe('sanitiseCue()', () => {
+  it('removes spaces', () => {
+    expect(sanitiseCue('  test')).toBe('test');
+    expect(sanitiseCue('  test   ')).toBe('test');
+    expect(sanitiseCue('test')).toBe('test');
+    expect(sanitiseCue('t e s t ')).toBe('test');
+  });
+  it('enforces . as decimals', () => {
+    expect(sanitiseCue('1,2')).toBe('1.2');
+    expect(sanitiseCue('1,2,3')).toBe('1.2.3');
+  });
+});

packages/utils/src/cue-utils/cueUtils.ts

@@ -0,0 +1,80 @@
+import { OntimeEvent, OntimeRundown } from 'ontime-types';
+
+import { getFirstEvent, getNextEvent } from '../rundown-utils/rundownUtils.js';
+import { isNumeric } from '../types/types.js';
+
+/**
+ * Finds if last characters in input are a number and increments
+ * @param input {string}
+ */
+export function getIncrement(input: string): string {
+  // Check if the input string contains a number at the end
+  const match = input.match(/^(\D*)(\d+)(\.\d+)?$/);
+
+  if (match) {
+    // If a number is found, extract the non-numeric prefix, integer part, and decimal part
+    let [, prefix, integerPart, decimalPart] = match;
+
+    if (decimalPart) {
+      if (decimalPart === '.99') {
+        decimalPart = '.100';
+      } else {
+        const addDecimal = '0'.repeat(decimalPart.length - 2) + '1';
+        const incrementedDecimal = (Number(decimalPart) + Number('0.' + addDecimal)).toFixed(decimalPart.length - 1);
+        decimalPart = incrementedDecimal.toString().replace('0.', '.');
+      }
+      return `${prefix}${integerPart}${decimalPart}`;
+    }
+    const incrementedInteger = Number(integerPart) + 1;
+    integerPart = incrementedInteger.toString();
+    return `${prefix}${integerPart}`;
+  }
+  // If no number is found, append "2" to the string and return the updated string
+  return input + '2';
+}
+
+/**
+ * Gets suitable name for a new event cue
+ * @param rundown {OntimeRundown}
+ * @param insertAfterId {string}
+ */
+export function getCueCandidate(rundown: OntimeRundown, insertAfterId?: string): string {
+  function addAtTop() {
+    const firstEventCue = getFirstEvent(rundown)?.cue;
+
+    if (isNumeric(firstEventCue)) {
+      return (Number(firstEventCue) / 10).toString();
+    }
+    return '1';
+  }
+
+  // we did not provide a element to go after, we attempt to go first so only need to check for a cue with value 1
+  if (typeof insertAfterId === 'undefined' || rundown.length === 0) {
+    return addAtTop();
+  }
+
+  const afterIndex = rundown.findIndex((event) => event.id === insertAfterId);
+
+  // we did not find the previous element, insert at top
+  if (afterIndex === -1) {
+    return addAtTop();
+  }
+
+  // get elements around
+  const previousEvent = rundown.at(afterIndex);
+  const nextEvent = getNextEvent(rundown, insertAfterId);
+
+  // try and increment the cue
+  let cue = getIncrement((previousEvent as OntimeEvent).cue);
+
+  // if increment is clashing with next, we add a decimal instead
+  if (cue === nextEvent?.cue) {
+    cue = (previousEvent as OntimeEvent).cue + '.1';
+  }
+
+  return cue;
+}
+
+export function sanitiseCue(cue: string) {
+  return cue.replaceAll(' ', '').replaceAll(',', '.');
+}

packages/utils/src/rundown-utils/rundownUtils.test.ts

@@ -1,6 +1,77 @@
+import { OntimeRundown, SupportedEvent } from 'ontime-types';
+
 import { dayInMs } from '../timeConstants.js';
+import { getNextEvent, getPreviousEvent } from './rundownUtils';
 import { calculateDuration } from './rundownUtils.js';
 
+describe('getNextEvent()', () => {
+  it('returns the next event of type event', () => {
+    const testRundown = [
+      { id: '1', type: SupportedEvent.Event },
+      { id: '2', type: SupportedEvent.Event },
+      { id: '3', type: SupportedEvent.Event },
+    ];
+
+    const next = getNextEvent(testRundown as OntimeRundown, '1');
+    expect(next?.id).toBe('2');
+  });
+  it('ignores other event types', () => {
+    const testRundown = [
+      { id: '1', type: SupportedEvent.Event },
+      { id: '2', type: SupportedEvent.Delay },
+      { id: '3', type: SupportedEvent.Block },
+      { id: '4', type: SupportedEvent.Event },
+    ];
+
+    const next = getNextEvent(testRundown as OntimeRundown, '1');
+    expect(next?.id).toBe('4');
+  });
+  it('returns null if none found', () => {
+    const testRundown = [
+      { id: '1', type: SupportedEvent.Event },
+      { id: '2', type: SupportedEvent.Delay },
+      { id: '3', type: SupportedEvent.Block },
+    ];
+
+    const next = getNextEvent(testRundown as OntimeRundown, '1');
+    expect(next).toBe(null);
+  });
+});
+
+describe('getPreviousEvent()', () => {
+  it('returns the previous event of type event', () => {
+    const testRundown = [
+      { id: '1', type: SupportedEvent.Event },
+      { id: '2', type: SupportedEvent.Event },
+      { id: '3', type: SupportedEvent.Event },
+    ];
+
+    const previous = getPreviousEvent(testRundown as OntimeRundown, '3');
+    expect(previous?.id).toBe('2');
+  });
+  it('ignores other event types', () => {
+    const testRundown = [
+      { id: '1', type: SupportedEvent.Event },
+      { id: '2', type: SupportedEvent.Delay },
+      { id: '3', type: SupportedEvent.Block },
+      { id: '4', type: SupportedEvent.Event },
+    ];
+
+    const previous = getPreviousEvent(testRundown as OntimeRundown, '4');
+    expect(previous?.id).toBe('1');
+  });
+  it('returns null if none found', () => {
+    const testRundown = [
+      { id: '2', type: SupportedEvent.Delay },
+      { id: '3', type: SupportedEvent.Block },
+      { id: '4', type: SupportedEvent.Event },
+    ];
+
+    const previous = getNextEvent(testRundown as OntimeRundown, '1');
+    expect(previous).toBe(null);
+  });
+});
+
 describe('calculateDuration()', () => {
   describe('Given start and end values', () => {
     it('is the difference between end and start', () => {
@@ -12,16 +83,8 @@ describe('calculateDuration()', () => {
   describe('Handles edge cases', () => {
     it('handles events that go over midnight', () => {
       const duration = calculateDuration(51, 50);
-      expect(duration).not.toBe(-50);
       expect(duration).toBe(dayInMs - 1);
     });
-    it('when both are equal', () => {
-      const testStart = 1;
-      const testEnd = 1;
-      const val = calculateDuration(testStart, testEnd);
-      expect(val).toBe(testEnd - testStart);
-    });
-
     it('handles no difference', () => {
       const duration1 = calculateDuration(0, 0);
       const duration2 = calculateDuration(dayInMs, dayInMs);

packages/utils/src/rundown-utils/rundownUtils.ts

@@ -1,7 +1,100 @@
-import { OntimeEvent, OntimeRundown } from 'ontime-types';
+import { OntimeEvent, OntimeRundown, OntimeRundownEntry, SupportedEvent } from 'ontime-types';
 
 import { dayInMs } from '../timeConstants.js';
 
+/**
+ * Gets first event in rundown, if it exists
+ * @param {OntimeRundownEntry[]} rundown
+ * @return {OntimeRundownEntry | null}
+ */
+export function getFirst(rundown: OntimeRundownEntry[]) {
+  return rundown.length ? rundown[0] : null;
+}
+
+/**
+ * Gets first scheduled event in rundown, if it exists
+ * @param {OntimeRundownEntry[]} rundown
+ * @return {OntimeEvent | null}
+ */
+export function getFirstEvent(rundown: OntimeRundownEntry[]) {
+  for (let i = 0; i < rundown.length; i++) {
+    if (rundown[i].type === SupportedEvent.Event) {
+      return rundown[i] as OntimeEvent;
+    }
+  }
+  return null;
+}
+
+/**
+ * Gets next event in rundown, if it exists
+ * @param {OntimeRundownEntry[]} rundown
+ * @param {string} currentId
+ * @return {OntimeRundownEntry | null}
+ */
+export function getNext(rundown: OntimeRundownEntry[], currentId: string): OntimeRundownEntry | null {
+  const index = rundown.findIndex((event) => event.id === currentId);
+  if (index !== -1 && index + 1 < rundown.length) {
+    return rundown[index + 1];
+  } else {
+    return null;
+  }
+}
+
+/**
+ * Gets next scheduled event in rundown, if it exists
+ * @param {OntimeRundownEntry[]} rundown
+ * @param {string} currentId
+ * @return {OntimeEvent | null}
+ */
+export function getNextEvent(rundown: OntimeRundownEntry[], currentId: string): OntimeEvent | null {
+  const index = rundown.findIndex((event) => event.id === currentId);
+  if (index < 0) {
+    return null;
+  }
+
+  for (let i = index + 1; i < rundown.length; i++) {
+    if (rundown[i].type === SupportedEvent.Event) {
+      return rundown[i] as OntimeEvent;
+    }
+  }
+  return null;
+}
+
+/**
+ * Gets previous event in rundown, if it exists
+ * @param {OntimeRundownEntry[]} rundown
+ * @param {string} currentId
+ * @return {OntimeRundownEntry | null}
+ */
+export function getPrevious(rundown: OntimeRundownEntry[], currentId: string) {
+  const index = rundown.findIndex((event) => event.id === currentId);
+  if (index !== -1 && index - 1 >= 0) {
+    return rundown[index - 1];
+  } else {
+    return null;
+  }
+}
+
+/**
+ * Gets previous scheduled event in rundown, if it exists
+ * @param {OntimeRundownEntry[]} rundown
+ * @param {string} currentId
+ * @return {OntimeEvent | null}
+ */
+export function getPreviousEvent(rundown: OntimeRundownEntry[], currentId: string): OntimeEvent | null {
+  const index = rundown.findIndex((event) => event.id === currentId);
+  if (index < 0) {
+    return null;
+  }
+
+  for (let i = index - 1; i >= 0; i--) {
+    if (rundown[i].type === SupportedEvent.Event) {
+      return rundown[i] as OntimeEvent;
+    }
+  }
+  return null;
+}
+
 /**
  * @description calculates event duration considering midnight
  * @param {number} timeStart

packages/utils/src/types/types.test.ts

@@ -0,0 +1,18 @@
+import { isNumeric } from './types.js';
+
+describe('isNumeric()', () => {
+  it('identifies numeric values', () => {
+    const testCases = [12, 12.3, Infinity, -Infinity, 0, -0];
+
+    for (const tc of testCases) {
+      expect(isNumeric(tc)).toBe(true);
+    }
+  });
+  it('identifies string version of numeric values', () => {
+    const testCases = ['12', '12.3', 'Infinity', '-Infinity', '0', '-0'];
+
+    for (const tc of testCases) {
+      expect(isNumeric(tc)).toBe(true);
+    }
+  });
+});

packages/utils/src/types/types.ts

@@ -0,0 +1,11 @@
+export function isNumeric(num: any) {
+  if (typeof num === 'number' && !isNaN(num)) {
+    return true;
+  }
+
+  if (typeof num === 'string' && num.trim() !== '') {
+    return !isNaN(parseFloat(num));
+  }
+
+  return false;
+}