@synnaxlabs/x 0.11.0 → 0.13.0

package/src/spatial/position/position.ts

@@ -0,0 +1,174 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { type Alignment, type XLocation, type YLocation } from "@/spatial/base";
+import { box } from "@/spatial/box";
+import { direction } from "@/spatial/direction";
+import { location } from "@/spatial/location";
+import { xy } from "@/spatial/xy";
+
+export const posititonSoVisible = (target: HTMLElement, p: xy.XY): [xy.XY, boolean] => {
+  const { width, height } = target.getBoundingClientRect();
+  const { innerWidth, innerHeight } = window;
+  let changed = false;
+  let nextXY = xy.construct(p);
+  if (p.x + width > innerWidth) {
+    nextXY = xy.translateX(nextXY, -width);
+    changed = true;
+  }
+  if (p.y + height > innerHeight) {
+    nextXY = xy.translateY(nextXY, -height);
+    changed = true;
+  }
+  return [nextXY, changed];
+};
+
+export interface DialogProps {
+  container: box.Crude;
+  target: box.Crude;
+  dialog: box.Crude;
+  alignments?: Alignment[];
+  initial?: location.Outer | Partial<location.XY> | location.XY;
+  prefer?: Array<location.Outer | Partial<location.XY> | location.XY>;
+  disable?: Array<location.Location | Partial<location.XY>>;
+}
+
+const parseLocationOptions = (
+  initial?: location.Outer | Partial<location.XY> | location.XY,
+): Partial<location.XY> => {
+  if (initial == null) return { x: undefined, y: undefined };
+  const parsedXYLoc = location.xy.safeParse(initial);
+  if (parsedXYLoc.success) return parsedXYLoc.data;
+  const parsedLoc = location.location.safeParse(initial);
+  if (parsedLoc.success) {
+    const isX = direction.construct(parsedLoc.data) === "x";
+    return isX
+      ? { x: parsedLoc.data as XLocation, y: undefined }
+      : { x: undefined, y: parsedLoc.data as YLocation };
+  }
+  return initial as Partial<location.XY>;
+};
+
+export interface DialogReturn {
+  location: location.XY;
+  adjustedDialog: box.Box;
+}
+
+export const dialog = ({
+  container: containerCrude,
+  target: targetCrude,
+  dialog: dialogCrude,
+  initial,
+  prefer,
+  alignments = ["start"],
+  disable = [],
+}: DialogProps): DialogReturn => {
+  const initialLocs = parseLocationOptions(initial);
+
+  let options = location.XY_LOCATIONS;
+  if (prefer != null) {
+    const parsedPrefer = prefer.map((p) => parseLocationOptions(p));
+    options = options.slice().sort((a, b) => {
+      const hasPreferA = parsedPrefer.findIndex((p) => location.xyMatches(a, p));
+      const hasPreferB = parsedPrefer.findIndex((p) => location.xyMatches(b, p));
+      if (hasPreferA > -1 && hasPreferB > -1) return hasPreferA - hasPreferB;
+      if (hasPreferA > -1) return -1;
+      if (hasPreferB > -1) return 1;
+      return 0;
+    });
+  }
+  const mappedOptions = options
+    .filter(
+      (l) =>
+        !location.xyEquals(l, location.CENTER) &&
+        (initialLocs.x == null || l.x === initialLocs.x) &&
+        (initialLocs.y == null || l.y === initialLocs.y) &&
+        !disable.some((d) => location.xyMatches(l, d)),
+    )
+    .map((l) => alignments?.map((a) => [l, a]))
+    .flat() as Array<[location.XY, Alignment]>;
+
+  const container = box.construct(containerCrude);
+  const target = box.construct(targetCrude);
+  const dialog = box.construct(dialogCrude);
+
+  // maximum value of a number in js
+  let bestOptionArea = -Infinity;
+  const res: DialogReturn = { location: location.CENTER, adjustedDialog: dialog };
+  mappedOptions.forEach(([option, alignment]) => {
+    const [adjustedBox, area] = evaluateOption({
+      option,
+      alignment,
+      container,
+      target,
+      dialog,
+    });
+    if (area > bestOptionArea) {
+      bestOptionArea = area;
+      res.location = option;
+      res.adjustedDialog = adjustedBox;
+    }
+  });
+
+  return res;
+};
+
+interface EvaluateOptionProps {
+  option: location.XY;
+  alignment: Alignment;
+  container: box.Box;
+  target: box.Box;
+  dialog: box.Box;
+}
+
+const evaluateOption = ({
+  option,
+  alignment,
+  container,
+  target,
+  dialog,
+}: EvaluateOptionProps): [box.Box, number] => {
+  const root = getRoot(option, alignment);
+  const targetPoint = box.xyLoc(target, option);
+  const dialogBox = box.constructWithAlternateRoot(
+    targetPoint.x,
+    targetPoint.y,
+    box.width(dialog),
+    box.height(dialog),
+    root,
+    location.TOP_LEFT,
+  );
+  const area = box.area(box.intersect(dialogBox, container));
+  return [dialogBox, area];
+};
+
+const X_ALIGNMENT_MAP: Record<Alignment, location.X | location.Center> = {
+  start: "left",
+  center: "center",
+  end: "right",
+};
+
+const Y_ALIGNMENT_MAP: Record<Alignment, location.Y | location.Center> = {
+  start: "bottom",
+  center: "center",
+  end: "top",
+};
+
+export const getRoot = (option: location.XY, alignment: Alignment): location.XY => {
+  const out: location.XY = { x: "center", y: "center" };
+  if (option.y !== "center") {
+    out.y = location.swap(option.y) as location.Y;
+    const swapper = option.x === "left" ? location.swap : (v: location.Location) => v;
+    out.x = swapper(X_ALIGNMENT_MAP[alignment]) as location.X;
+  } else {
+    out.x = location.swap(option.x) as location.X;
+    out.y = Y_ALIGNMENT_MAP[alignment];
+  }
+  return out;
+};

package/src/spatial/scale/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+export * as scale from "@/spatial/scale/scale";

package/src/spatial/{scale.spec.ts → scale/scale.spec.ts}

@@ -9,8 +9,8 @@
 
 import { describe, it, expect, test } from "vitest";
 
-import * as box from "@/spatial/box";
-import { XY, Scale } from "@/spatial/scale";
+import * as box from "@/spatial/box/box";
+import { XY, Scale } from "@/spatial/scale/scale";
 
 type ScaleSpec = [name: string, scale: Scale, i: number, o: number];
 

package/src/spatial/{scale.ts → scale/scale.ts}

@@ -10,12 +10,12 @@
 import { z } from "zod";
 
 import { clamp } from "@/clamp";
-import * as bounds from "@/spatial/bounds";
-import { type Box, isBox } from "@/spatial/box";
-import * as box from "@/spatial/box";
-import type * as dims from "@/spatial/dimensions";
-import * as location from "@/spatial/location";
-import * as xy from "@/spatial/xy";
+import * as bounds from "@/spatial/bounds/bounds";
+import { type Box, isBox } from "@/spatial/box/box";
+import * as box from "@/spatial/box/box";
+import type * as dims from "@/spatial/dimensions/dimensions";
+import * as location from "@/spatial/location/location";
+import * as xy from "@/spatial/xy/xy";
 
 export const crudeXYTransform = z.object({ offset: xy.crudeZ, scale: xy.crudeZ });
 

package/src/spatial/xy/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+export * as xy from "@/spatial/xy/xy";

package/src/spatial/{xy.spec.ts → xy/xy.spec.ts}

@@ -9,7 +9,7 @@
 
 import { describe, expect, test } from "vitest";
 
-import * as xy from "@/spatial/xy";
+import * as xy from "@/spatial/xy/xy";
 
 describe("XY", () => {
   describe("construction", () => {

package/src/spatial/{xy.ts → xy/xy.ts}

@@ -44,7 +44,12 @@ export type Crude = z.infer<typeof crudeZ>;
  * @param y - If x is a number, the y coordinate. If x is a number and this argument is
  * not given, the y coordinate is assumed to be the same as the x coordinate.
  */
-export const construct = (x: Crude, y?: number): XY => {
+export const construct = (x: Crude | Direction, y?: number): XY => {
+  if (typeof x === "string") {
+    if (y === undefined) throw new Error("The y coordinate must be given.");
+    if (x === "x") return { x: y, y: 0 };
+    return { x: 0, y };
+  }
   // The order in which we execute these checks is very important.
   if (typeof x === "number") return { x, y: y ?? x };
   if (Array.isArray(x)) return { x: x[0], y: x[1] };
@@ -98,19 +103,14 @@ export const translateY = (c: Crude, y: number): XY => {
   return { x: p.x, y: p.y + y };
 };
 
-type TranslateOverloadOne = (a: Crude, b: Crude, ...cb: Crude[]) => XY;
-type TranslateOverloadTwo = (a: Crude, direction: Direction, value: number) => XY;
+interface Translate {
+  /** @returns the sum of the given coordinates. */
+  (a: Crude, b: Crude, ...cb: Crude[]): XY;
+  /** @returns the coordinates translated in the given direction by the given value. */
+  (a: Crude, direction: Direction, value: number): XY;
+}
 
-/**
- * @returns the given coordinate translated by an arbitrary number of translation
- * coordinates.
- */
-export const translate: TranslateOverloadOne & TranslateOverloadTwo = (
-  a,
-  b,
-  v,
-  ...cb
-): XY => {
+export const translate: Translate = (a, b, v, ...cb): XY => {
   if (typeof b === "string" && typeof v === "number") {
     if (b === "x") return translateX(a, v);
     return translateY(a, v);
@@ -172,7 +172,7 @@ export const isNan = (a: Crude): boolean => {
 export const isFinite = (a: Crude): boolean => {
   const xy = construct(a);
   return Number.isFinite(xy.x) && Number.isFinite(xy.y);
-}
+};
 
 /** @returns the coordinate represented as a couple of the form [x, y]. */
 export const couple = (a: Crude): NumberCouple => {
@@ -185,3 +185,8 @@ export const css = (a: Crude): { left: number; top: number } => {
   const xy = construct(a);
   return { left: xy.x, top: xy.y };
 };
+
+export const truncate = (a: Crude, precision: number = 0): XY => {
+  const xy = construct(a);
+  return { x: Number(xy.x.toFixed(precision)), y: Number(xy.y.toFixed(precision)) };
+};

package/src/telem/series.spec.ts

@@ -21,8 +21,8 @@ describe("Series", () => {
       expect(a.dataType.toString()).toBe(DataType.FLOAT32.toString());
       expect(a.length).toEqual(3);
       expect(a.byteLength).toEqual(Size.bytes(12));
-      expect(a.byteCap).toEqual(Size.bytes(12));
-      expect(a.cap).toEqual(3);
+      expect(a.byteCapacity).toEqual(Size.bytes(12));
+      expect(a.capacity).toEqual(3);
       const b = new Series({ data: new BigInt64Array([BigInt(1)]) });
       expect(b.dataType.toString()).toBe(DataType.INT64.toString());
       const c = new Series({
@@ -55,15 +55,15 @@ describe("Series", () => {
 
     describe("allocation", () => {
       it("should allocate a lazy array", () => {
-        const series = Series.alloc({ length: 10, dataType: DataType.FLOAT32 });
-        expect(series.byteCap).toEqual(Size.bytes(40));
-        expect(series.cap).toEqual(10);
+        const series = Series.alloc({ capacity: 10, dataType: DataType.FLOAT32 });
+        expect(series.byteCapacity).toEqual(Size.bytes(40));
+        expect(series.capacity).toEqual(10);
         expect(series.length).toEqual(0);
         expect(series.byteLength).toEqual(Size.bytes(0));
       });
       it("should throw an error when attempting to allocate an array of lenght 0", () => {
         expect(() => {
-          Series.alloc({ length: 0, dataType: DataType.FLOAT32 });
+          Series.alloc({ capacity: 0, dataType: DataType.FLOAT32 });
         }).toThrow();
       });
     });
@@ -87,8 +87,26 @@ describe("Series", () => {
       });
       expect(series.at(3)).toBeUndefined();
     });
+    it("should allow the index to be negative", () => {
+      const series = new Series({
+        data: new Float32Array([1, 2, 3]),
+        dataType: DataType.FLOAT32,
+      });
+      expect(series.at(-1)).toEqual(3);
+    });
+    it("should throw an error when the index is out of bounds and require is set to true", () => {
+      const series = new Series({
+        data: new Float32Array([1, 2, 3]),
+        dataType: DataType.FLOAT32,
+      });
+      expect(() => {
+        series.at(3, true);
+      }).toThrow();
+    });
   });
 
+
+
   describe("slice", () => {
     it("should slice a lazy array", () => {
       const a = new Series({
@@ -100,14 +118,14 @@ describe("Series", () => {
       expect(b.data).toEqual(new Float32Array([2]));
       expect(b.length).toEqual(1);
       expect(b.byteLength).toEqual(Size.bytes(4));
-      expect(b.byteCap).toEqual(Size.bytes(4));
-      expect(b.cap).toEqual(1);
+      expect(b.byteCapacity).toEqual(Size.bytes(4));
+      expect(b.capacity).toEqual(1);
     });
   });
 
   describe("min and max", () => {
     it("should return a min and max of zero on an allocated array", () => {
-      const series = Series.alloc({ length: 10, dataType: DataType.FLOAT32 });
+      const series = Series.alloc({ capacity: 10, dataType: DataType.FLOAT32 });
       expect(series.max).toEqual(-Infinity);
       expect(series.min).toEqual(Infinity);
     });
@@ -154,8 +172,8 @@ describe("Series", () => {
 
   describe("writing", () => {
     it("should correctly write to an allocated lazy array", () => {
-      const series = Series.alloc({ length: 10, dataType: DataType.FLOAT32 });
-      expect(series.byteCap).toEqual(Size.bytes(40));
+      const series = Series.alloc({ capacity: 10, dataType: DataType.FLOAT32 });
+      expect(series.byteCapacity).toEqual(Size.bytes(40));
       expect(series.length).toEqual(0);
       const writeOne = new Series({ data: new Float32Array([1]) });
       expect(series.write(writeOne)).toEqual(1);
@@ -165,7 +183,7 @@ describe("Series", () => {
       expect(series.length).toEqual(3);
     });
     it("should recompute cached max and min correctly", () => {
-      const series = Series.alloc({ length: 10, dataType: DataType.FLOAT32 });
+      const series = Series.alloc({ capacity: 10, dataType: DataType.FLOAT32 });
       series.enrich();
       const writeTwo = new Series({ data: new Float32Array([2, 3]) });
       series.write(writeTwo);
@@ -174,7 +192,7 @@ describe("Series", () => {
     });
     it("should correctly adjust the sample offset of a written array", () => {
       const series = Series.alloc({
-        length: 2,
+        capacity: 2,
         dataType: DataType.FLOAT32,
         timeRange: TimeRange.ZERO,
         sampleOffset: -3,
@@ -200,7 +218,7 @@ describe("Series", () => {
       expect(ts.timeRange).toEqual(
         new TimeRange(TimeStamp.seconds(1), TimeStamp.seconds(6)),
       );
-      expect(ts.cap).toEqual(5);
+      expect(ts.capacity).toEqual(5);
       expect(ts.length).toEqual(5);
       expect(ts.dataType.toString()).toEqual(DataType.TIMESTAMP.toString());
       expect(ts.data).toEqual(
@@ -233,7 +251,7 @@ describe("Series", () => {
       expect(buf).toEqual(new Float32Array([1, 2, 3]));
     });
     it("should correctly update a buffer when writing to an allocated array", () => {
-      const series = Series.alloc({ length: 10, dataType: DataType.FLOAT32 });
+      const series = Series.alloc({ capacity: 10, dataType: DataType.FLOAT32 });
       const controller = new MockGLBufferController();
       series.updateGLBuffer(controller);
       expect(controller.createBufferMock).toHaveBeenCalledTimes(1);
@@ -249,7 +267,7 @@ describe("Series", () => {
       expect(controller.bufferDataMock).toHaveBeenCalledTimes(1);
       expect(controller.bufferSubDataMock).toHaveBeenCalledTimes(1);
       buf = controller.buffers[series.glBuffer as number];
-      expect(buf.byteLength).toEqual(series.byteCap.valueOf());
+      expect(buf.byteLength).toEqual(series.byteCapacity.valueOf());
       expect(new Float32Array(buf)[0]).toEqual(1);
       const writeTwo = new Series({ data: new Float32Array([2, 3]) });
       series.write(writeTwo);
@@ -257,7 +275,7 @@ describe("Series", () => {
       expect(controller.bufferDataMock).not.toHaveBeenCalledTimes(2);
       expect(controller.bufferSubDataMock).toHaveBeenCalledTimes(2);
       buf = controller.buffers[series.glBuffer as number];
-      expect(buf.byteLength).toEqual(series.byteCap.valueOf());
+      expect(buf.byteLength).toEqual(series.byteCapacity.valueOf());
       expect(new Float32Array(buf)[0]).toEqual(1);
       expect(new Float32Array(buf)[1]).toEqual(2);
       expect(new Float32Array(buf)[2]).toEqual(3);
@@ -286,7 +304,7 @@ describe("Series", () => {
       series.acquire(controller);
       expect(controller.createBufferMock).toHaveBeenCalledTimes(2);
       const buf = controller.buffers[series.glBuffer as number];
-      expect(buf.byteLength).toEqual(series.byteCap.valueOf());
+      expect(buf.byteLength).toEqual(series.byteCapacity.valueOf());
     });
   });
 
@@ -341,7 +359,7 @@ describe("Series", () => {
 
   describe("binarySearch", () => {
     it("should correctly binary search a pre-allocated array", () => {
-      const series = Series.alloc({ length: 10, dataType: DataType.FLOAT32 });
+      const series = Series.alloc({ capacity: 10, dataType: DataType.FLOAT32 });
       const writeOne = new Series({ data: new Float32Array([1, 2, 3, 4, 5]) });
       series.write(writeOne);
       expect(series.binarySearch(3)).toEqual(2);

package/src/telem/series.ts

@@ -26,12 +26,6 @@ import {
 
 export type SampleValue = number | bigint;
 
-const validateFieldNotNull = (name: string, field: unknown): void => {
-  if (field == null) {
-    throw new Error(`field ${name} is null`);
-  }
-};
-
 interface GL {
   control: GLBufferController | null;
   buffer: WebGLBuffer | null;
@@ -46,6 +40,7 @@ export interface SeriesDigest {
   alignment: bounds.Bounds;
   timeRange?: string;
   length: number;
+  capacity: number;
 }
 
 interface BaseSeriesProps {
@@ -62,7 +57,7 @@ export interface SeriesProps extends BaseSeriesProps {
 }
 
 export interface SeriesAllocProps extends BaseSeriesProps {
-  length: number;
+  capacity: number;
   dataType: CrudeDataType;
 }
 
@@ -106,7 +101,7 @@ export class Series {
   /** Tracks the number of entities currently using this array. */
   private _refCount: number = 0;
 
-  static alloc({ length, dataType, ...props }: SeriesAllocProps): Series {
+  static alloc({ capacity: length, dataType, ...props }: SeriesAllocProps): Series {
     if (length === 0)
       throw new Error("[Series] - cannot allocate an array of length 0");
     const data = new new DataType(dataType).Array(length);
@@ -188,13 +183,21 @@ export class Series {
       throw new Error("cannot release an array with a negative reference count");
   }
 
+  /**
+   * Writes the given series to this series. If the series being written exceeds the
+   * remaining of series being written to, only the portion that fits will be written.
+   * @param other the series to write to this series. The data type of the series written
+   * must be the same as the data type of the series being written to.
+   * @returns the number of samples written. If the entire series fits, this value is
+   * equal to the length of the series being written.
+   */
   write(other: Series): number {
     if (!other.dataType.equals(this.dataType))
       throw new Error("buffer must be of the same type as this array");
 
     // We've filled the entire underlying buffer
     if (this.writePos === FULL_BUFFER) return 0;
-    const available = this.cap - this.writePos;
+    const available = this.capacity - this.writePos;
 
     const toWrite = available < other.length ? other.slice(0, available) : other;
     this.underlyingData.set(toWrite.data as any, this.writePos);
@@ -252,23 +255,23 @@ export class Series {
 
   /** @returns the time range of this array. */
   get timeRange(): TimeRange {
-    validateFieldNotNull("timeRange", this._timeRange);
-    return this._timeRange!;
+    if (this._timeRange == null) throw new Error("time range not set on series");
+    return this._timeRange;
   }
 
-  /** @returns the capacity of the underlying buffer in bytes. */
-  get byteCap(): Size {
+  /** @returns the capacity of the series in bytes. */
+  get byteCapacity(): Size {
     return new Size(this.buffer.byteLength);
   }
 
-  /** @returns the capacity of the underlying buffer in samples. */
-  get cap(): number {
-    return this.dataType.density.length(this.byteCap);
+  /** @returns the capacity of the series in samples. */
+  get capacity(): number {
+    return this.dataType.density.length(this.byteCapacity);
   }
 
-  /** @returns the length of the underlying buffer in samples. */
+  /** @returns the length of the series in bytes. */
   get byteLength(): Size {
-    if (this.writePos === FULL_BUFFER) return this.byteCap;
+    if (this.writePos === FULL_BUFFER) return this.byteCapacity;
     return this.dataType.density.size(this.writePos);
   }
 
@@ -371,9 +374,17 @@ export class Series {
     return addSamples(this.max, -this.min);
   }
 
-  at(index: number): SampleValue {
+  at(index: number, required: true): SampleValue;
+
+  at(index: number, required?: false): SampleValue | undefined;
+
+  at(index: number, required?: boolean): SampleValue | undefined {
+    if (index < 0) index = this.length + index;
     const v = this.data[index];
-    if (v == null) return undefined as any;
+    if (v == null) {
+      if (required) throw new Error(`[series] - no value at index ${index}`);
+      return undefined;
+    }
     return addSamples(v, this.sampleOffset);
   }
 
@@ -388,7 +399,7 @@ export class Series {
     const cf = compare.newF(value);
     while (left <= right) {
       const mid = Math.floor((left + right) / 2);
-      const cmp = cf(this.at(mid), value);
+      const cmp = cf(this.at(mid, true), value);
       if (cmp === 0) return mid;
       if (cmp < 0) left = mid + 1;
       else right = mid - 1;
@@ -414,7 +425,7 @@ export class Series {
     // This means we only need to buffer part of the array.
     if (this.writePos !== FULL_BUFFER) {
       if (prevBuffer === 0) {
-        gl.bufferData(gl.ARRAY_BUFFER, this.byteCap.valueOf(), gl.STATIC_DRAW);
+        gl.bufferData(gl.ARRAY_BUFFER, this.byteCapacity.valueOf(), gl.STATIC_DRAW);
       }
       const byteOffset = this.dataType.density.size(prevBuffer).valueOf();
       const slice = this.underlyingData.slice(this.gl.prevBuffer, this.writePos);
@@ -439,6 +450,7 @@ export class Series {
       alignment: this.alignmentBounds,
       timeRange: this._timeRange?.toString(),
       length: this.length,
+      capacity: this.capacity,
     };
   }