@synnaxlabs/x 0.7.0

package/src/spatial/position.ts

@@ -0,0 +1,26 @@
+// 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 * as 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];
+};

package/src/spatial/scale.spec.ts

@@ -0,0 +1,74 @@
+// 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, it, expect, test } from "vitest";
+
+import * as box from "@/spatial/box";
+import { XY, Scale } from "@/spatial/scale";
+
+type ScaleSpec = [name: string, scale: Scale, i: number, o: number];
+
+describe("Scale", () => {
+  describe("Scale", () => {
+    const simpleScale = Scale.scale(0, 10).scale(0, 1);
+    const translateScale = Scale.scale(0, 10).translate(5).scale(0, 1);
+    const translateMagnifyScale = Scale.scale(0, 10)
+      .translate(5)
+      .magnify(2)
+      .scale(0, 1);
+    describe("position", () => {
+      const positionSpecs: ScaleSpec[] = [
+        ["basic", simpleScale, 0, 0],
+        ["basic II", simpleScale, 5, 0.5],
+        ["reverse basic", simpleScale.reverse(), 0, 0],
+        ["reverse basic II", simpleScale.reverse(), 0.5, 5],
+        ["translate", translateScale, 0, 0.5],
+        ["translate II", translateScale, 5, 1],
+        ["reverse translate", translateScale.reverse(), 0.5, 0],
+        ["reverse translate II", translateScale.reverse(), 0, -5],
+        ["translate magnify", translateMagnifyScale, 0, 1],
+        ["translate magnify II", translateMagnifyScale, 5, 2],
+        ["reverse translate magnify", translateMagnifyScale.reverse(), 1, 0],
+        ["reverse translate magnify II", translateMagnifyScale.reverse(), 0, -5],
+      ];
+      positionSpecs.forEach(([name, scale, i, o]) => {
+        it(`should return ${o} for ${i} on ${name}`, () => {
+          expect(scale.pos(i)).toBe(o);
+        });
+      });
+    });
+    describe("dimension", () => {
+      const dimensionSpecs: ScaleSpec[] = [
+        ["basic", simpleScale, 0, 0],
+        ["basic II", simpleScale, 5, 0.5],
+        ["reverse basic", simpleScale.reverse(), 0, 0],
+        ["reverse basic II", simpleScale.reverse(), 0.5, 5],
+        ["translate", translateScale, 0, 0],
+        ["translate II", translateScale, 5, 0.5],
+        ["reverse translate", translateScale.reverse(), 0.5, 5],
+        ["translate magnify", translateMagnifyScale, 0, 0],
+        ["translate magnify II", translateMagnifyScale, 5, 1],
+      ];
+      dimensionSpecs.forEach(([name, scale, i, o]) => {
+        it(`should return ${o} for ${i} on ${name}`, () =>
+          expect(scale.dim(i)).toBe(o));
+      });
+    });
+    describe("XYScale", () => {
+      test("converting a DOM rect to decimal coordinates", () => {
+        const s = XY.scale(box.construct(100, 100, 1000, 1000)).scale(box.DECIMAL);
+        const b1 = s.box(box.construct(100, 100, 1000, 1000));
+        expect(box.bottomLeft(b1)).toEqual({ x: 0, y: 0 });
+        const b2 = s.box(box.construct(200, 200, 200, 200));
+        expect(box.bottomLeft(b2).x).toBeCloseTo(0.1);
+        expect(box.bottomLeft(b2).y).toBeCloseTo(0.7);
+      });
+    });
+  });
+});

package/src/spatial/scale.ts

@@ -0,0 +1,351 @@
+// 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 { 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";
+
+export const crudeXYTransform = z.object({ offset: xy.crudeZ, scale: xy.crudeZ });
+
+export type XYTransformT = z.infer<typeof crudeXYTransform>;
+
+export type BoundVariant = "domain" | "range";
+
+type ValueType = "position" | "dimension";
+
+type Operation = (
+  currScale: bounds.Bounds | null,
+  type: ValueType,
+  number: number,
+  reverse: boolean,
+) => OperationReturn;
+
+type OperationReturn = [bounds.Bounds | null, number];
+
+interface TypedOperation extends Operation {
+  type: "translate" | "magnify" | "scale" | "invert" | "clamp" | "re-bound";
+}
+
+const curriedTranslate =
+  (translate: number): Operation =>
+  (currScale, type, v, reverse) => {
+    if (type === "dimension") return [currScale, v];
+    return [currScale, reverse ? v - translate : v + translate];
+  };
+
+const curriedMagnify =
+  (magnify: number): Operation =>
+  (currScale, _type, v, reverse) => [currScale, reverse ? v / magnify : v * magnify];
+
+const curriedScale =
+  (bound: bounds.Bounds): Operation =>
+  (currScale, type, v) => {
+    if (currScale === null) return [bound, v];
+    const { lower: prevLower, upper: prevUpper } = currScale;
+    const { lower: nextLower, upper: nextUpper } = bound;
+    const prevRange = prevUpper - prevLower;
+    const nextRange = nextUpper - nextLower;
+    if (type === "dimension") return [bound, v * (nextRange / prevRange)];
+    const nextV = (v - prevLower) * (nextRange / prevRange) + nextLower;
+    return [bound, nextV];
+  };
+
+const curriedReBound =
+  (bound: bounds.Bounds): Operation =>
+  (currScale, type, v) => [bound, v];
+
+const curriedInvert = (): Operation => (currScale, type, v) => {
+  if (currScale === null) throw new Error("cannot invert without bounds");
+  if (type === "dimension") return [currScale, v];
+  const { lower, upper } = currScale;
+  return [currScale, upper - (v - lower)];
+};
+
+const curriedClamp =
+  (bound: bounds.Bounds): Operation =>
+  (currScale, _, v) => {
+    const { lower, upper } = bound;
+    v = clamp(v, lower, upper);
+    return [currScale, v];
+  };
+
+export class Scale {
+  ops: TypedOperation[] = [];
+  currBounds: bounds.Bounds | null = null;
+  currType: ValueType | null = null;
+  private reversed = false;
+
+  constructor() {
+    this.ops = [];
+  }
+
+  static translate(value: number): Scale {
+    return new Scale().translate(value);
+  }
+
+  static magnify(value: number): Scale {
+    return new Scale().magnify(value);
+  }
+
+  static scale(lowerOrBound: number | bounds.Bounds, upper?: number): Scale {
+    return new Scale().scale(lowerOrBound, upper);
+  }
+
+  translate(value: number): Scale {
+    const next = this.new();
+    const f = curriedTranslate(value) as TypedOperation;
+    f.type = "translate";
+    next.ops.push(f);
+    return next;
+  }
+
+  magnify(value: number): Scale {
+    const next = this.new();
+    const f = curriedMagnify(value) as TypedOperation;
+    f.type = "magnify";
+    next.ops.push(f);
+    return next;
+  }
+
+  scale(lowerOrBound: number | bounds.Bounds, upper?: number): Scale {
+    const b = bounds.construct(lowerOrBound, upper);
+    const next = this.new();
+    const f = curriedScale(b) as TypedOperation;
+    f.type = "scale";
+    next.ops.push(f);
+    return next;
+  }
+
+  clamp(lowerOrBound: number | bounds.Bounds, upper?: number): Scale {
+    const b = bounds.construct(lowerOrBound, upper);
+    const next = this.new();
+    const f = curriedClamp(b) as TypedOperation;
+    f.type = "clamp";
+    next.ops.push(f);
+    return next;
+  }
+
+  reBound(lowerOrBound: number | bounds.Bounds, upper?: number): Scale {
+    const b = bounds.construct(lowerOrBound, upper);
+    const next = this.new();
+    const f = curriedReBound(b) as TypedOperation;
+    f.type = "re-bound";
+    next.ops.push(f);
+    return next;
+  }
+
+  invert(): Scale {
+    const f = curriedInvert() as TypedOperation;
+    f.type = "invert";
+    const next = this.new();
+    next.ops.push(f);
+    return next;
+  }
+
+  pos(v: number): number {
+    return this.exec("position", v);
+  }
+
+  dim(v: number): number {
+    return this.exec("dimension", v);
+  }
+
+  private new(): Scale {
+    const scale = new Scale();
+    scale.ops = this.ops.slice();
+    scale.reversed = this.reversed;
+    return scale;
+  }
+
+  private exec(vt: ValueType, v: number): number {
+    this.currBounds = null;
+    return this.ops.reduce<OperationReturn>(
+      ([b, v]: OperationReturn, op: Operation): OperationReturn =>
+        op(b, vt, v, this.reversed),
+      [null, v],
+    )[1];
+  }
+
+  reverse(): Scale {
+    const scale = this.new();
+    scale.ops.reverse();
+    // Switch the order of the operations to place scale operation 'BEFORE' the subsequent
+    // non - scale operations for example, if we have a reversed [scale A, scale B,
+    // translate A, magnify, translate B, scale C] we want to reverse it to [scale C,
+    // scale B, translate B, magnify, translate A, scale A]
+    const swaps: Array<[number, number]> = [];
+    scale.ops.forEach((op, i) => {
+      if (op.type === "scale" || swaps.some(([low, high]) => i >= low && i <= high))
+        return;
+      const nextScale = scale.ops.findIndex((op, j) => op.type === "scale" && j > i);
+      if (nextScale === -1) return;
+      swaps.push([i, nextScale]);
+    });
+    swaps.forEach(([low, high]) => {
+      const s = scale.ops.slice(low, high);
+      s.unshift(scale.ops[high]);
+      scale.ops.splice(low, high - low + 1, ...s);
+    });
+    scale.reversed = !scale.reversed;
+    return scale;
+  }
+
+  static readonly IDENTITY = new Scale();
+}
+
+export const xyScaleToTransform = (scale: XY): XYTransformT => ({
+  scale: {
+    x: scale.x.dim(1),
+    y: scale.y.dim(1),
+  },
+  offset: {
+    x: scale.x.pos(0),
+    y: scale.y.pos(0),
+  },
+});
+
+export class XY {
+  x: Scale;
+  y: Scale;
+  currRoot: location.CornerXY | null;
+
+  constructor(
+    x: Scale = new Scale(),
+    y: Scale = new Scale(),
+    root: location.CornerXY | null = null,
+  ) {
+    this.x = x;
+    this.y = y;
+    this.currRoot = root;
+  }
+
+  static translate(xy: number | xy.XY, y?: number): XY {
+    return new XY().translate(xy, y);
+  }
+
+  static translateX(x: number): XY {
+    return new XY().translateX(x);
+  }
+
+  static translateY(y: number): XY {
+    return new XY().translateY(y);
+  }
+
+  static clamp(box: Box): XY {
+    return new XY().clamp(box);
+  }
+
+  static magnify(xy: xy.XY): XY {
+    return new XY().magnify(xy);
+  }
+
+  static scale(box: dims.Dimensions | Box): XY {
+    return new XY().scale(box);
+  }
+
+  static reBound(box: Box): XY {
+    return new XY().reBound(box);
+  }
+
+  translate(cp: number | xy.Crude, y?: number): XY {
+    const _xy = xy.construct(cp, y);
+    const next = this.copy();
+    next.x = this.x.translate(_xy.x);
+    next.y = this.y.translate(_xy.y);
+    return next;
+  }
+
+  translateX(x: number): XY {
+    const next = this.copy();
+    next.x = this.x.translate(x);
+    return next;
+  }
+
+  translateY(y: number): XY {
+    const next = this.copy();
+    next.y = this.y.translate(y);
+    return next;
+  }
+
+  magnify(xy: xy.XY): XY {
+    const next = this.copy();
+    next.x = this.x.magnify(xy.x);
+    next.y = this.y.magnify(xy.y);
+    return next;
+  }
+
+  scale(b: Box | dims.Dimensions): XY {
+    const next = this.copy();
+    if (isBox(b)) {
+      const prevRoot = this.currRoot;
+      next.currRoot = b.root;
+      if (prevRoot != null && !location.xyEquals(prevRoot, b.root)) {
+        if (prevRoot.x !== b.root.x) next.x = next.x.invert();
+        if (prevRoot.y !== b.root.y) next.y = next.y.invert();
+      }
+      next.x = next.x.scale(box.xBounds(b));
+      next.y = next.y.scale(box.yBounds(b));
+      return next;
+    }
+    next.x = next.x.scale(b.width);
+    next.y = next.y.scale(b.height);
+    return next;
+  }
+
+  reBound(b: Box): XY {
+    const next = this.copy();
+    next.x = this.x.reBound(box.xBounds(b));
+    next.y = this.y.reBound(box.yBounds(b));
+    return next;
+  }
+
+  clamp(b: Box): XY {
+    const next = this.copy();
+    next.x = this.x.clamp(box.xBounds(b));
+    next.y = this.y.clamp(box.yBounds(b));
+    return next;
+  }
+
+  copy(): XY {
+    const n = new XY();
+    n.currRoot = this.currRoot;
+    n.x = this.x;
+    n.y = this.y;
+    return n;
+  }
+
+  reverse(): XY {
+    const next = this.copy();
+    next.x = this.x.reverse();
+    next.y = this.y.reverse();
+    return next;
+  }
+
+  pos(xy: xy.XY): xy.XY {
+    return { x: this.x.pos(xy.x), y: this.y.pos(xy.y) };
+  }
+
+  box(b: Box): Box {
+    return box.construct(
+      this.pos(b.one),
+      this.pos(b.two),
+      0,
+      0,
+      this.currRoot ?? b.root,
+    );
+  }
+
+  static readonly IDENTITY = new XY();
+}

package/src/spatial/spatial.ts

@@ -0,0 +1,17 @@
+// 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 {
+  ALIGNMENTS,
+  alignment,
+  type Alignment,
+  ORDERS,
+  order,
+  type Order,
+} from "@/spatial/base";

package/src/spatial/xy.spec.ts

@@ -0,0 +1,68 @@
+// 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, test } from "vitest";
+
+import * as xy from "@/spatial/xy";
+
+describe("XY", () => {
+  describe("construction", () => {
+    [
+      ["from object", { x: 1, y: 2 }],
+      ["from couple", [1, 2]],
+      ["from dimensions", { width: 1, height: 2 }],
+      ["from signed dimensions", { signedWidth: 1, signedHeight: 2 }],
+      ["from client dimensions", { clientX: 1, clientY: 2 }],
+    ].forEach(([name, arg]) => {
+      test(name as string, () => {
+        const p = xy.construct(arg as xy.Crude);
+        expect(p.x).toEqual(1);
+        expect(p.y).toEqual(2);
+      });
+    });
+  });
+});
+test("translateX", () => {
+  let p = xy.construct([1, 2]);
+  p = xy.translateX(p, 5);
+  expect(p.x).toEqual(6);
+  expect(p.y).toEqual(2);
+});
+test("translateY", () => {
+  let p = xy.construct([1, 2]);
+  p = xy.translateY(p, 5);
+  expect(p.x).toEqual(1);
+  expect(p.y).toEqual(7);
+});
+test("translate", () => {
+  let p = xy.construct([1, 2]);
+  p = xy.translate(p, [5, 5]);
+  expect(p.x).toEqual(6);
+  expect(p.y).toEqual(7);
+});
+describe("equals", () => {
+  const TESTS: Array<[xy.Crude, xy.Crude, boolean]> = [
+    [[1, 1], { x: 1, y: 1 }, true],
+    [[1, 1], [1, 1], true],
+    [{ x: 1, y: 12 }, { x: 1, y: 1 }, false],
+    [{ x: 1, y: 12 }, { width: 1, height: 12 }, true],
+    [{ x: 1, y: 12 }, { width: 12, height: 1 }, false],
+    [{ x: 1, y: 12 }, { signedWidth: 1, signedHeight: 12 }, true],
+  ];
+  TESTS.forEach(([one, two, expected], i) => {
+    test(`equals ${i}`, () => {
+      const p = xy.construct(one);
+      expect(xy.equals(p, two)).toEqual(expected);
+    });
+  });
+});
+test("couple", () => {
+  const p = xy.construct([1, 2]);
+  expect(xy.couple(p)).toEqual([1, 2]);
+});

package/src/spatial/xy.ts

@@ -0,0 +1,164 @@
+// 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 { z } from "zod";
+
+import {
+  clientXY,
+  dimensions,
+  numberCouple,
+  xy,
+  type NumberCouple,
+  type ClientXY,
+  type XY,
+  signedDimensions,
+  type Direction,
+} from "@/spatial/base";
+
+export { clientXY, xy, type ClientXY as Client, type XY };
+
+/** A crude representation of a {@link XY} coordinate as a zod schema. */
+export const crudeZ = z.union([
+  xy,
+  numberCouple,
+  dimensions,
+  signedDimensions,
+  clientXY,
+]);
+
+/** A crude representation of a {@link XY} coordinate. */
+export type Crude = z.infer<typeof crudeZ>;
+
+/**
+ * @constructs XY
+ * @param x - A crude representation of the XY coordinate as a number, number couple,
+ * dimensions, signed dimensions, or client XY.
+ * @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 | number, y?: number): XY => {
+  if (typeof x === "number") return { x, y: y ?? x };
+  if (Array.isArray(x)) return { x: x[0], y: x[1] };
+  if ("signedWidth" in x) return { x: x.signedWidth, y: x.signedHeight };
+  if ("clientX" in x) return { x: x.clientX, y: x.clientY };
+  if ("width" in x) return { x: x.width, y: x.height };
+  return { ...x };
+};
+
+/** An x and y coordinate of zero */
+export const ZERO = { x: 0, y: 0 };
+
+/** An x and y coordinate of one */
+export const ONE = { x: 1, y: 1 };
+
+/** An x and y coordinate of infinity */
+export const INFINITY = { x: Infinity, y: Infinity };
+
+/** An x and y coordinate of NaN */
+export const NAN = { x: NaN, y: NaN };
+
+/** @returns true if the two XY coordinates are semntically equal. */
+export const equals = (a: Crude, b: Crude): boolean => {
+  const a_ = construct(a);
+  const b_ = construct(b);
+  return a_.x === b_.x && a_.y === b_.y;
+};
+
+/** Is zero is true if the XY coordinate has a semantic x and y value of zero. */
+export const isZero = (c: Crude): boolean => equals(c, ZERO);
+
+/**
+ * @returns the given coordinate scaled by the given factors. If only one factor is given,
+ * the y factor is assumed to be the same as the x factor.
+ */
+export const scale = (c: Crude, x: number, y: number = x): XY => {
+  const p = construct(c);
+  return { x: p.x * x, y: p.y * y };
+};
+
+/** @returns the given coordinate translated in the X direction by the given amount. */
+export const translateX = (c: Crude, x: number): XY => {
+  const p = construct(c);
+  return { x: p.x + x, y: p.y };
+};
+
+/** @returns the given coordinate translated in the Y direction by the given amount. */
+export const translateY = (c: Crude, y: number): XY => {
+  const p = construct(c);
+  return { x: p.x, y: p.y + y };
+};
+
+/**
+ * @returns the given coordinate translated by an arbitrary number of translation
+ * coordinates.
+ */
+export const translate = (a: Crude, b: Crude, ...cb: Crude[]): XY =>
+  [a, b, ...cb].reduce((p: XY, c) => {
+    const xy = construct(c);
+    return { x: p.x + xy.x, y: p.y + xy.y };
+  }, ZERO);
+
+/**
+ * @returns the given coordinate the given direction set to the given value.
+ * @example set({ x: 1, y: 2 }, "x", 3) // { x: 3, y: 2 }
+ */
+export const set = (c: Crude, direction: Direction, value: number): XY => {
+  const xy = construct(c);
+  if (direction === "x") return { x: value, y: xy.y };
+  return { x: xy.x, y: value };
+};
+
+/** @returns the magnitude of the distance between the two given coordinates. */
+export const distance = (ca: Crude, cb: Crude): number => {
+  const a = construct(ca);
+  const b = construct(cb);
+  return Math.sqrt((a.x - b.x) ** 2 + (a.y - b.y) ** 2);
+};
+
+/** @returns the magnitude of the x distance between the two given coordinates. */
+export const xDistance = (ca: Crude, cb: Crude): number => {
+  const a = construct(ca);
+  const b = construct(cb);
+  return Math.abs(a.x - b.x);
+};
+
+/** @returns the magnitude of the y distance between the two given coordinates. */
+export const yDistance = (ca: Crude, cb: Crude): number => {
+  const a = construct(ca);
+  const b = construct(cb);
+  return Math.abs(a.y - b.y);
+};
+
+/**
+ * @returns the translation that would need to be applied to move the first coordinate
+ * to the second coordinate.
+ */
+export const translation = (ca: Crude, cb: Crude): XY => {
+  const a = construct(ca);
+  const b = construct(cb);
+  return { x: b.x - a.x, y: b.y - a.y };
+};
+
+/** @returns true if both the x and y coordinates of the given coordinate are NaN. */
+export const isNan = (a: Crude): boolean => {
+  const xy = construct(a);
+  return Number.isNaN(xy.x) || Number.isNaN(xy.y);
+};
+
+/** @returns the coordinate represented as a couple of the form [x, y]. */
+export const couple = (a: Crude): NumberCouple => {
+  const xy = construct(a);
+  return [xy.x, xy.y];
+};
+
+/** @returns the coordinate represented as css properties in the form { left, top }. */
+export const css = (a: Crude): { left: number; top: number } => {
+  const xy = construct(a);
+  return { left: xy.x, top: xy.y };
+};