@synnaxlabs/x 0.12.0 → 0.14.1

package/src/spatial/position/position.spec.ts

@@ -0,0 +1,211 @@
+// 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 { describe, expect, it } from "vitest";
+
+import { box } from "@/spatial";
+import { type Alignment } from "@/spatial/base";
+import { location } from "@/spatial/location";
+import { position } from "@/spatial/position";
+
+type Spec = [position.DialogProps, location.XY];
+
+describe("position", () => {
+  describe("dialog", () => {
+    const SPEC_CASE_1: Spec = [
+      {
+        container: box.construct(0, 0, 100, 100),
+        target: box.construct(45, 55, 10, 10),
+        dialog: box.construct(0, 0, 20, 20),
+      },
+      location.LEFT_CENTER,
+    ];
+
+    const SPEC_CASE_2: Spec = [
+      {
+        container: box.construct(0, 0, 100, 100),
+        target: box.construct(45, 55, 10, 10),
+        dialog: box.construct(0, 0, 20, 20),
+        initial: "top",
+      },
+      location.TOP_CENTER,
+    ];
+
+    const SPEC_CASE_3: Spec = [
+      {
+        container: box.construct(0, 0, 100, 100),
+        target: box.construct(45, 55, 10, 10),
+        dialog: box.construct(0, 0, 20, 20),
+        initial: "bottom",
+      },
+      location.BOTTOM_CENTER,
+    ];
+
+    const SPEC_CASE_4: Spec = [
+      {
+        container: box.construct(0, 0, 100, 100),
+        target: box.construct(45, 55, 10, 10),
+        dialog: box.construct(0, 0, 20, 20),
+        initial: "left",
+      },
+      location.LEFT_CENTER,
+    ];
+
+    const SPEC_CASE_5: Spec = [
+      {
+        container: box.construct(0, 0, 100, 100),
+        target: box.construct(45, 55, 10, 10),
+        dialog: box.construct(0, 0, 20, 20),
+        initial: "right",
+      },
+      location.RIGHT_CENTER,
+    ];
+
+    // Target is in bottom right corner
+    const SPEC_CASE_6: Spec = [
+      {
+        container: box.construct(0, 0, 100, 100),
+        target: box.construct(90, 90, 10, 10),
+        dialog: box.construct(0, 0, 20, 20),
+      },
+      location.LEFT_CENTER,
+    ];
+
+    // Target is in the top left corner
+    const SPEC_CASE_7: Spec = [
+      {
+        container: box.construct(0, 0, 100, 100),
+        target: box.construct(0, 0, 10, 10),
+        dialog: box.construct(0, 0, 20, 20),
+      },
+      location.BOTTOM_CENTER,
+    ];
+
+    const SPEC_CASE_8: Spec = [
+      {
+        container: {
+          one: { x: 0, y: 0 },
+          two: { x: 1707, y: 1075 },
+          root: { x: "left", y: "top" },
+        },
+        target: {
+          one: { x: 79, y: 965 },
+          two: { x: 1647, y: 992 },
+          root: { x: "left", y: "top" },
+        },
+        dialog: {
+          one: { x: 79.53125, y: 781 },
+          two: { x: 1647.53125, y: 1141 },
+          root: { x: "left", y: "top" },
+        },
+        initial: { x: "center" },
+        alignments: ["center"],
+      },
+      location.TOP_CENTER,
+    ];
+
+    const SPEC_CASE_9: Spec = [
+      {
+        container: {
+          one: { x: 0, y: 0 },
+          two: { x: 1707, y: 697 },
+          root: { x: "left", y: "top" },
+        },
+        target: {
+          one: { x: 79, y: 587 },
+          two: { x: 1647, y: 614 },
+          root: { x: "left", y: "top" },
+        },
+        dialog: {
+          one: { x: 79, y: 991 },
+          two: { x: 1647, y: 1351 },
+          root: { x: "left", y: "top" },
+        },
+        initial: { x: "center" },
+        alignments: ["center"],
+      },
+      location.TOP_CENTER,
+    ];
+
+    // const SPEC_CASE_10 = [
+    //   {
+    //     container: {
+    //       one: { x: 0, y: 0 },
+    //       two: { x: 1707, y: 697 },
+    //       root: { x: "left", y: "top" },
+    //     },
+    //     target: {
+    //       one: { x: 78, y: 4 },
+    //       two: { x: 278, y: 31 },
+    //       root: { x: "left", y: "top" },
+    //     },
+    //     dialog: {
+    //       one: { x: 78, y: 4 },
+    //       two: { x: 78, y: 4 },
+    //       root: { x: "left", y: "top" },
+    //     },
+    //     alignments: ["end"],
+    //     disable: ["center"],
+    //   },
+    //   location.BOTTOM_LEFT,
+    // ];
+
+    const SPECS: Spec[] = [
+      SPEC_CASE_1,
+      SPEC_CASE_2,
+      SPEC_CASE_3,
+      SPEC_CASE_4,
+      SPEC_CASE_5,
+      SPEC_CASE_6,
+      SPEC_CASE_7,
+      SPEC_CASE_8,
+      SPEC_CASE_9,
+      // SPEC_CASE_10,
+    ];
+
+    SPECS.forEach(([props, expected]) => {
+      it(`should position dialog correctly`, () => {
+        expect(position.dialog(props).location).toEqual(expected);
+      });
+    });
+  });
+  describe("getRoot", () => {
+    const SPECS: Array<[location.XY, Alignment, location.XY]> = [
+      [location.TOP_LEFT, "start", location.BOTTOM_RIGHT],
+      [location.TOP_LEFT, "center", location.BOTTOM_CENTER],
+      [location.TOP_LEFT, "end", location.BOTTOM_LEFT],
+      [location.TOP_RIGHT, "start", location.BOTTOM_LEFT],
+      [location.TOP_RIGHT, "center", location.BOTTOM_CENTER],
+      [location.TOP_RIGHT, "end", location.BOTTOM_RIGHT],
+      [location.TOP_CENTER, "start", location.BOTTOM_LEFT],
+      [location.TOP_CENTER, "center", location.BOTTOM_CENTER],
+      [location.TOP_CENTER, "end", location.BOTTOM_RIGHT],
+      [location.LEFT_CENTER, "start", location.BOTTOM_RIGHT],
+      [location.LEFT_CENTER, "center", location.RIGHT_CENTER],
+      [location.LEFT_CENTER, "end", location.TOP_RIGHT],
+      [location.RIGHT_CENTER, "start", location.BOTTOM_LEFT],
+      [location.RIGHT_CENTER, "center", location.LEFT_CENTER],
+      [location.RIGHT_CENTER, "end", location.TOP_LEFT],
+      [location.BOTTOM_LEFT, "start", location.TOP_RIGHT],
+      [location.BOTTOM_LEFT, "center", location.TOP_CENTER],
+      [location.BOTTOM_LEFT, "end", location.TOP_LEFT],
+      [location.BOTTOM_RIGHT, "start", location.TOP_LEFT],
+      [location.BOTTOM_RIGHT, "center", location.TOP_CENTER],
+      [location.BOTTOM_RIGHT, "end", location.TOP_RIGHT],
+      [location.BOTTOM_CENTER, "start", location.TOP_LEFT],
+      [location.BOTTOM_CENTER, "center", location.TOP_CENTER],
+      [location.BOTTOM_CENTER, "end", location.TOP_RIGHT],
+    ];
+    SPECS.forEach(([option, order, expected]) => {
+      it(`should position get the correct positioning root for ${location.xyToString(option)} and ${order}`, () => {
+        expect(position.getRoot(option, order)).toEqual(expected);
+      });
+    });
+  });
+});

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

@@ -50,7 +50,7 @@ describe("Series", () => {
         dataType: DataType.FLOAT32,
         timeRange: new TimeRange(1, 2),
       });
-      expect(a.timeRange.span.valueOf()).toBe(1);
+      expect(a.timeRange.span.valueOf()).toBe(1n);
     });
 
     describe("allocation", () => {
@@ -105,8 +105,6 @@ describe("Series", () => {
     });
   });
 
-
-
   describe("slice", () => {
     it("should slice a lazy array", () => {
       const a = new Series({

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 {
@@ -189,8 +184,8 @@ export class Series {
   }
 
   /**
-   * 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. 
+   * 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
@@ -260,8 +255,8 @@ 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 series in bytes. */
@@ -455,6 +450,7 @@ export class Series {
       alignment: this.alignmentBounds,
       timeRange: this._timeRange?.toString(),
       length: this.length,
+      capacity: this.capacity,
     };
   }