@synnaxlabs/x 0.7.0

package/src/spatial/box.ts

@@ -0,0 +1,326 @@
+// 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 type * as bounds from "@/spatial/bounds";
+import type * as dimensions from "@/spatial/dimensions";
+import * as direction from "@/spatial/direction";
+import * as location from "@/spatial/location";
+import * as xy from "@/spatial/xy";
+
+const cssPos = z.union([z.number(), z.string()]);
+
+const cssBox = z.object({
+  top: cssPos,
+  left: cssPos,
+  width: cssPos,
+  height: cssPos,
+});
+const domRect = z.object({
+  left: z.number(),
+  top: z.number(),
+  right: z.number(),
+  bottom: z.number(),
+});
+export const box = z.object({
+  one: xy.xy,
+  two: xy.xy,
+  root: location.corner,
+});
+
+export type Box = z.infer<typeof box>;
+export type CSS = z.infer<typeof cssBox>;
+export type DOMRect = z.infer<typeof domRect>;
+
+type Crude = DOMRect | Box | { getBoundingClientRect: () => DOMRect };
+
+/** A box centered at (0,0) with a width and height of 0. */
+export const ZERO = { one: xy.ZERO, two: xy.ZERO, root: location.TOP_LEFT };
+
+/**
+ * A box centered at (0,0) with a width and height of 1, and rooted in the
+ * bottom left. Note that pixel space is typically rooted in the top left.
+ */
+export const DECIMAL = { one: xy.ZERO, two: xy.ONE, root: location.BOTTOM_LEFT };
+
+export const copy = (b: Box, root?: location.CornerXY): Box => ({
+  one: b.one,
+  two: b.two,
+  root: root ?? b.root,
+});
+
+/**
+ * Box represents a general box in 2D space. It typically represents a bounding box
+ * for a DOM element, but can also represent a box in clip space or decimal space.
+ *
+ * It'simportant to note that the behavior of a Box varies depending on its coordinate
+ * system.Make sure you're aware of which coordinate system you're using.
+ *
+ * Many of the properties and methods on a Box access the same semantic value. The
+ * different accessors are there for ease of use and semantics.
+ */
+export const construct = (
+  first: number | DOMRect | xy.XY | Box | { getBoundingClientRect: () => DOMRect },
+  second?: number | xy.XY | dimensions.Dimensions | dimensions.Signed,
+  width: number = 0,
+  height: number = 0,
+  coordinateRoot?: location.CornerXY,
+): Box => {
+  const b: Box = {
+    one: { ...xy.ZERO },
+    two: { ...xy.ZERO },
+    root: coordinateRoot ?? location.TOP_LEFT,
+  };
+
+  if (typeof first === "number") {
+    if (typeof second !== "number")
+      throw new Error("Box constructor called with invalid arguments");
+    b.one = { x: first, y: second };
+    b.two = { x: b.one.x + width, y: b.one.y + height };
+    return b;
+  }
+
+  if ("one" in first && "two" in first && "root" in first)
+    return { ...first, root: coordinateRoot ?? first.root };
+
+  if ("getBoundingClientRect" in first) first = first.getBoundingClientRect();
+  if ("left" in first) {
+    b.one = { x: first.left, y: first.top };
+    b.two = { x: first.right, y: first.bottom };
+    return b;
+  }
+
+  b.one = first;
+  if (second == null) b.two = { x: b.one.x + width, y: b.one.y + height };
+  else if (typeof second === "number")
+    b.two = { x: b.one.x + second, y: b.one.y + width };
+  else if ("width" in second)
+    b.two = {
+      x: b.one.x + second.width,
+      y: b.one.y + second.height,
+    };
+  else if ("signedWidth" in second)
+    b.two = {
+      x: b.one.x + second.signedWidth,
+      y: b.one.y + second.signedHeight,
+    };
+  else b.two = second;
+  return b;
+};
+
+/**
+ * Checks if a box contains a point or another box.
+ *
+ * @param value - The point or box to check.
+ * @returns true if the box inclusively contains the point or box and false otherwise.
+ */
+export const contains = (b: Crude, value: Box | xy.XY): boolean => {
+  const b_ = construct(b);
+  if ("one" in value)
+    return (
+      left(value) >= left(b_) &&
+      right(value) <= right(b_) &&
+      top(value) >= top(b_) &&
+      bottom(value) <= bottom(b_)
+    );
+  return (
+    value.x >= left(b_) &&
+    value.x <= right(b_) &&
+    value.y >= top(b_) &&
+    value.y <= bottom(b_)
+  );
+};
+
+/**
+ * @returns true if the given box is semantically equal to this box and false otherwise.
+ */
+export const equals = (a: Box, b: Box): boolean =>
+  xy.equals(a.one, b.one) &&
+  xy.equals(a.two, b.two) &&
+  location.xyEquals(a.root, b.root);
+
+/**
+ * @returns the dimensions of the box. Note that these dimensions are guaranteed to
+ * be positive. To get the signed dimensions, use the `signedDims` property.
+ */
+export const dims = (b: Box): dimensions.Dimensions => ({
+  width: width(b),
+  height: height(b),
+});
+
+/**
+ * @returns the dimensions of the box. Note that these dimensions may be negative.
+ * To get the unsigned dimensions, use the `dims` property.
+ */
+export const signedDims = (b: Box): dimensions.Signed => ({
+  signedWidth: signedWidth(b),
+  signedHeight: signedHeight(b),
+});
+
+/**
+ * @returns the css representation of the box.
+ */
+export const css = (b: Box): CSS => ({
+  top: top(b),
+  left: left(b),
+  width: width(b),
+  height: height(b),
+});
+
+export const dim = (
+  b: Crude,
+  dir: direction.Crude,
+  signed: boolean = false,
+): number => {
+  const dim: number =
+    direction.construct(dir) === "y" ? signedHeight(b) : signedWidth(b);
+  return signed ? dim : Math.abs(dim);
+};
+
+/** @returns the pont corresponding to the given corner of the box. */
+export const xyLoc = (b: Crude, l: location.XY): xy.XY => {
+  const b_ = construct(b);
+  return {
+    x: l.x === "center" ? center(b_).x : loc(b_, l.x),
+    y: l.y === "center" ? center(b_).y : loc(b_, l.y),
+  };
+};
+
+/**
+ * @returns a one dimensional coordinate corresponding to the location of the given
+ * side of the box i.e. the x coordinate of the left side, the y coordinate of the
+ * top side, etc.
+ */
+export const loc = (b: Crude, loc: location.Location): number => {
+  const b_ = construct(b);
+  const f = location.xyCouple(b_.root).includes(loc) ? Math.min : Math.max;
+  return location.X_LOCATIONS.includes(loc as location.X)
+    ? f(b_.one.x, b_.two.x)
+    : f(b_.one.y, b_.two.y);
+};
+
+export const locPoint = (b: Box, loc_: location.Location): xy.XY => {
+  const l = loc(b, loc_);
+  if (location.X_LOCATIONS.includes(loc_ as location.X))
+    return { x: l, y: center(b).y };
+  return { x: center(b).x, y: l };
+};
+
+export const isZero = (b: Box): boolean => {
+  return b.one.x === b.two.x && b.one.y === b.two.y;
+};
+
+export const width = (b: Crude): number => dim(b, "x");
+
+export const height = (b: Crude): number => dim(b, "y");
+
+export const signedWidth = (b: Crude): number => {
+  const b_ = construct(b);
+  return b_.two.x - b_.one.x;
+};
+
+export const signedHeight = (b: Crude): number => {
+  const b_ = construct(b);
+  return b_.two.y - b_.one.y;
+};
+
+export const topLeft = (b: Crude): xy.XY => xyLoc(b, location.TOP_LEFT);
+
+export const topRight = (b: Crude): xy.XY => xyLoc(b, location.TOP_RIGHT);
+
+export const bottomLeft = (b: Crude): xy.XY => xyLoc(b, location.BOTTOM_LEFT);
+
+export const bottomRight = (b: Crude): xy.XY => xyLoc(b, location.BOTTOM_RIGHT);
+
+export const right = (b: Crude): number => loc(b, "right");
+
+export const bottom = (b: Crude): number => loc(b, "bottom");
+
+export const left = (b: Crude): number => loc(b, "left");
+
+export const top = (b: Crude): number => loc(b, "top");
+
+export const center = (b: Crude): xy.XY =>
+  xy.translate(topLeft(b), {
+    x: signedWidth(b) / 2,
+    y: signedHeight(b) / 2,
+  });
+
+export const x = (b: Crude): number => {
+  const b_ = construct(b);
+  return b_.root.x === "left" ? left(b_) : right(b_);
+};
+
+export const y = (b: Crude): number => {
+  const b_ = construct(b);
+  return b_.root.y === "top" ? top(b_) : bottom(b_);
+};
+
+export const root = (b: Crude): xy.XY => ({ x: x(b), y: y(b) });
+
+export const xBounds = (b: Crude): bounds.Bounds => {
+  const b_ = construct(b);
+  return { lower: b_.one.x, upper: b_.two.x };
+};
+
+export const yBounds = (b: Crude): bounds.Bounds => {
+  const b_ = construct(b);
+  return { lower: b_.one.y, upper: b_.two.y };
+};
+
+export const reRoot = (b: Box, corner: location.CornerXY): Box => copy(b, corner);
+
+/**
+ * Reposition a box so that it is visible within a given bound.
+ *
+ * @param target The box to reposition - Only works if the root is topLeft
+ * @param bound The box to reposition within - Only works if the root is topLeft
+ *
+ * @returns the repsoitioned box and a boolean indicating if the box was repositioned
+ * or not.
+ */
+export const positionSoVisible = (
+  target_: Crude,
+  bound_: Crude,
+): [Box, boolean] => {
+  const target = construct(target_);
+  const bound = construct(bound_);
+  if (contains(bound, target)) return [target, false];
+  let nextPos: xy.XY;
+  if (right(target) > width(target))
+    nextPos = xy.construct({ x: x(target) - width(target), y: y(target) });
+  else nextPos = xy.construct({ x: x(target), y: y(target) - height(target) });
+  return [construct(nextPos, dims(target)), true];
+};
+
+/**
+ * Reposition a box so that it is centered within a given bound.
+ *
+ * @param target The box to reposition - Only works if the root is topLeft
+ * @param bound The box to reposition within - Only works if the root is topLeft
+ * @returns the repsoitioned box
+ */
+export const positionInCenter = (
+  target_: Crude,
+  bound_: Crude,
+): Box => {
+  const target = construct(target_);
+  const bound = construct(bound_);
+  const x_ = x(bound) + (width(bound) - width(target)) / 2;
+  const y_ = y(bound) + (height(bound) - height(target)) / 2;
+  return construct({ x: x_, y: y_ }, dims(target));
+};
+
+export const isBox = (value: unknown): value is Box => {
+  if (typeof value !== "object" || value == null) return false;
+  return "one" in value && "two" in value && "root" in value;
+};
+
+export const aspect = (b: Box): number => width(b) / height(b);

package/src/spatial/dimensions.spec.ts

@@ -0,0 +1,47 @@
+// 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 dimensions from "@/spatial/dimensions";
+
+describe("Dimensions", () => {
+  describe("construction", () => {
+    [
+      ["from object", { width: 1, height: 2 }],
+      ["from couple", [1, 2]],
+      ["from dimensions", { width: 1, height: 2 }],
+      ["from signed dimensions", { signedWidth: 1, signedHeight: 2 }],
+      ["from XY", { x: 1, y: 2 }],
+    ].forEach(([name, arg]) => {
+      test(name as string, () => {
+        const xy = dimensions.construct(arg as dimensions.Crude);
+        expect(xy.width).toEqual(1);
+        expect(xy.height).toEqual(2);
+      });
+    });
+  });
+  test("couple", () => {
+    const d = dimensions.construct([1, 2]);
+    expect(dimensions.couple(d)).toEqual([1, 2]);
+  });
+  describe("equals", () => {
+    type T = [dimensions.Crude, dimensions.Crude, boolean];
+    const TESTS: T[] = [
+      [[1, 1], { width: 1, height: 1 }, true],
+      [[1, 1], [1, 1], true],
+      [{ width: 1, height: 12 }, { width: 1, height: 1 }, false],
+      [{ width: 1, height: 12 }, { width: 12, height: 1 }, false],
+      [{ width: 1, height: 12 }, { signedWidth: 1, signedHeight: 12 }, true],
+    ];
+    TESTS.forEach(([one, two, expected], i) =>
+      test(`equals ${i}`, () => expect(dimensions.equals(one, two)).toEqual(expected)),
+    );
+  });
+});

package/src/spatial/dimensions.ts

@@ -0,0 +1,64 @@
+// 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 { dimensions, xy, type Dimensions, numberCouple } from "@/spatial/base";
+
+export { dimensions, type Dimensions };
+
+export const signed = z.object({ signedWidth: z.number(), signedHeight: z.number() });
+export const crude = z.union([dimensions, signed, xy, numberCouple]);
+export type Crude = z.infer<typeof crude>;
+
+export const ZERO = { width: 0, height: 0 };
+export const DECIMAL = { width: 1, height: 1 };
+
+export const construct = (width: number | Crude, height?: number): Dimensions => {
+  if (typeof width === "number") return { width, height: height ?? width };
+  if (Array.isArray(width)) return { width: width[0], height: width[1] };
+  if ("x" in width) return { width: width.x, height: width.y };
+  if ("signedWidth" in width)
+    return { width: width.signedWidth, height: width.signedHeight };
+  return { ...width };
+};
+
+export type Signed = z.infer<typeof signed>;
+
+export const equals = (ca: Crude, cb?: Crude | null): boolean => {
+  if (cb == null) return false;
+  const a = construct(ca);
+  const b = construct(cb);
+  return a.width === b.width && a.height === b.height;
+};
+
+export const swap = (ca: Crude): Dimensions => {
+  const a = construct(ca);
+  return { width: a.height, height: a.width };
+};
+
+export const svgViewBox = (ca: Crude): string => {
+  const a = construct(ca);
+  return `0 0 ${a.width} ${a.height}`;
+};
+
+export const couple = (ca: Crude): [number, number] => {
+  const a = construct(ca);
+  return [a.width, a.height];
+};
+
+export const max = (crude: Crude[]): Dimensions => ({
+  width: Math.max(...crude.map((c) => construct(c).width)),
+  height: Math.max(...crude.map((c) => construct(c).height)),
+});
+
+export const min = (crude: Crude[]): Dimensions => ({
+  width: Math.min(...crude.map((c) => construct(c).width)),
+  height: Math.min(...crude.map((c) => construct(c).height)),
+});

package/src/spatial/direction.spec.ts

@@ -0,0 +1,25 @@
+// 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 direction from "@/spatial/direction";
+
+describe("Direction", () => {
+  describe("construction", () => {
+    type T = [string, direction.Crude];
+    const TESTS: T[] = [
+      ["from location", "top"],
+      ["from literal", "y"],
+    ];
+    TESTS.forEach(([name, arg]) =>
+      test(name, () => expect(direction.construct(arg)).toEqual("y")),
+    );
+  });
+});

package/src/spatial/direction.ts

@@ -0,0 +1,47 @@
+// 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 Dimension,
+  type Direction,
+  type Location,
+  type direction,
+  DIRECTIONS,
+  Y_LOCATIONS,
+  type YLocation,
+  type SignedDimension,
+  crudeDirection,
+  type CrudeDirection,
+} from "@/spatial/base";
+
+export type { Direction, direction };
+
+export const crude = crudeDirection;
+
+export type Crude = CrudeDirection;
+
+export const construct = (c: Crude): Direction => {
+  if (DIRECTIONS.includes(c as Direction)) return c as Direction;
+  if (Y_LOCATIONS.includes(c as YLocation)) return "y";
+  else return "x";
+};
+
+export const swap = (direction: Direction): Direction =>
+  direction === "x" ? "y" : "x";
+
+export const dimension = (direction: Direction): Dimension =>
+  direction === "x" ? "width" : "height";
+
+export const location = (direction: Direction): Location =>
+  direction === "x" ? "left" : "top";
+
+export const isDirection = (c: unknown): c is Direction => crude.safeParse(c).success;
+
+export const signedDimension = (direction: Direction): SignedDimension =>
+  direction === "x" ? "signedWidth" : "signedHeight";

package/src/spatial/external.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 * as bounds from "@/spatial/bounds";
+export * as box from "@/spatial/box";
+export * as dimensions from "@/spatial/dimensions";
+export * as direction from "@/spatial/direction";
+export * as location from "@/spatial/location";
+export * as xy from "@/spatial/xy";
+export * as scale from "@/spatial/scale";
+export * as spatial from "@/spatial/spatial";

package/src/spatial/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 * from "@/spatial/external";

package/src/spatial/location.spec.ts

@@ -0,0 +1,24 @@
+// 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 location from "@/spatial/location";
+
+describe("Location", () => {
+  describe("construction", () => {
+    [
+      ["from valueOf", String("left")],
+      ["from string", "left"],
+      ["from direction", "x"],
+    ].forEach(([name, arg]) =>
+      test(name, () => expect(location.construct(arg)).toEqual("left")),
+    );
+  });
+});

package/src/spatial/location.ts

@@ -0,0 +1,124 @@
+// 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 { Case } from "@/case";
+import {
+  location,
+  type Location,
+  xLocation,
+  yLocation,
+  DIRECTIONS,
+  X_LOCATIONS,
+  Y_LOCATIONS,
+  CENTER_LOCATIONS,
+  type XLocation,
+  type OuterLocation,
+  type YLocation,
+  outerLocation,
+  type Direction,
+  crudeLocation,
+  type CrudeLocation,
+} from "@/spatial/base";
+
+export {
+  location,
+  type Location,
+  X_LOCATIONS,
+  Y_LOCATIONS,
+  CENTER_LOCATIONS,
+  outerLocation as outer,
+};
+
+export const x = xLocation;
+export const y = yLocation;
+
+export type X = XLocation;
+export type Y = YLocation;
+export type Outer = OuterLocation;
+
+const SWAPPED: Record<Location, Location> = {
+  top: "bottom",
+  right: "left",
+  bottom: "top",
+  left: "right",
+  center: "center",
+};
+
+export const crude = crudeLocation;
+
+export type Crude = CrudeLocation;
+
+export const construct = (cl: Crude): Location => {
+  if (cl instanceof String) return cl as Location;
+  if (!DIRECTIONS.includes(cl as Direction)) return cl as Location;
+  else if (cl === "x") return "left";
+  else return "top";
+};
+
+export const swap = (cl: Crude): Location => SWAPPED[construct(cl)];
+
+export const direction = (cl: Crude): Direction => {
+  const l = construct(cl);
+  if (l === "top" || l === "bottom") return "y";
+  return "x";
+};
+
+export const xy = z.object({ x: location, y: location });
+export const corner = z.object({ x: xLocation, y: yLocation });
+
+export type XY = z.infer<typeof xy>;
+export type CornerXY = z.infer<typeof corner>;
+
+export const TOP_LEFT: CornerXY = { x: "left", y: "top" };
+export const TOP_RIGHT: CornerXY = { x: "right", y: "top" };
+export const BOTTOM_LEFT: CornerXY = { x: "left", y: "bottom" };
+export const BOTTOM_RIGHT: CornerXY = { x: "right", y: "bottom" };
+export const CENTER: XY = { x: "center", y: "center" };
+export const TOP_CENTER: XY = { x: "center", y: "top" };
+export const BOTTOM_CENTER: XY = { x: "center", y: "bottom" };
+export const RIGHT_CENTER: XY = { x: "right", y: "center" };
+export const LEFT_CENTER: XY = { x: "left", y: "center" };
+
+export const xyEquals = (a: XY, b: XY): boolean => a.x === b.x && a.y === b.y;
+
+export const xyCouple = (a: XY): [Location, Location] => [a.x, a.y];
+
+export const isX = (a: Crude): boolean => direction(construct(a)) === "x";
+
+export const isY = (a: Crude): boolean => direction(construct(a)) === "y";
+
+export const xyToString = (a: XY): string => `${a.x}${Case.capitalize(a.y)}`;
+
+export const constructXY = (x: Crude | XY, y?: Crude): XY => {
+  let one: Location;
+  let two: Location;
+  if (typeof x === "object" && "x" in x) {
+    one = x.x;
+    two = x.y;
+  } else {
+    one = construct(x);
+    two = construct(y ?? x);
+  }
+  if (direction(one) === direction(two) && one !== "center" && two !== "center")
+    throw new Error(
+      `[XYLocation] - encountered two locations with the same direction: ${one.toString()} - ${two.toString()}`,
+    );
+  const xy = CENTER;
+  if (one === "center") {
+    if (direction(two) === "x") [xy.x, xy.y] = [two, one];
+    else [xy.x, xy.y] = [one, two];
+  } else if (two === "center") {
+    if (direction(one) === "x") [xy.x, xy.y] = [one, two];
+    else [xy.x, xy.y] = [two, one];
+  } else if (direction(one) === "x") [xy.x, xy.y] = [one, two];
+  else [xy.x, xy.y] = [two, one];
+  return xy;
+};