@synnaxlabs/x 0.44.2 → 0.44.4

package/src/spatial/direction/direction.spec.ts

@@ -7,7 +7,7 @@
 // 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 { describe, expect, it, test } from "vitest";
 
 import * as direction from "@/spatial/direction/direction";
 
@@ -22,4 +22,38 @@ describe("Direction", () => {
       test(name, () => expect(direction.construct(arg)).toEqual("y")),
     );
   });
+
+  describe("isX", () => {
+    const TESTS: [direction.Crude, boolean][] = [
+      ["x", true],
+      ["y", false],
+      ["left", true],
+      ["right", true],
+      ["top", false],
+      ["bottom", false],
+      ["center", false],
+    ];
+    TESTS.forEach(([arg, expected]) => {
+      it(`should return ${expected} for ${arg}`, () => {
+        expect(direction.isX(arg)).toBe(expected);
+      });
+    });
+  });
+
+  describe("isY", () => {
+    const TESTS: [direction.Crude, boolean][] = [
+      ["x", false],
+      ["y", true],
+      ["left", false],
+      ["right", false],
+      ["top", true],
+      ["bottom", true],
+      ["center", false],
+    ];
+    TESTS.forEach(([arg, expected]) => {
+      it(`should return ${expected} for ${arg}`, () => {
+        expect(direction.isY(arg)).toBe(expected);
+      });
+    });
+  });
 });

package/src/spatial/direction/direction.ts

@@ -10,6 +10,8 @@
 import {
   type CrudeDirection,
   crudeDirection,
+  type CrudeXDirection,
+  type CrudeYDirection,
   type Dimension,
   type Direction,
   direction,
@@ -25,6 +27,8 @@ export { Direction, direction, DIRECTIONS };
 export const crude = crudeDirection;
 
 export type Crude = CrudeDirection;
+export type CrudeX = CrudeXDirection;
+export type CrudeY = CrudeYDirection;
 
 export const construct = (c: Crude): Direction => {
   if (DIRECTIONS.includes(c as Direction)) return c as Direction;
@@ -45,3 +49,11 @@ export const isDirection = (c: unknown): c is Direction => crude.safeParse(c).su
 
 export const signedDimension = (direction: CrudeDirection): SignedDimension =>
   construct(direction) === "x" ? "signedWidth" : "signedHeight";
+
+export const isX = (direction: CrudeDirection): direction is CrudeXDirection => {
+  if (direction === "center") return false;
+  return construct(direction) === "x";
+};
+
+export const isY = (direction: CrudeDirection): direction is CrudeYDirection =>
+  construct(direction) === "y";

package/src/spatial/external.ts

@@ -12,7 +12,6 @@ export { box } from "@/spatial/box";
 export * from "@/spatial/dimensions";
 export * from "@/spatial/direction";
 export * from "@/spatial/location";
-export * from "@/spatial/position";
 export * from "@/spatial/scale";
 export * as spatial from "@/spatial/spatial";
 export * from "@/spatial/xy";

package/src/spatial/xy/xy.spec.ts

@@ -9,7 +9,8 @@
 
 import { describe, expect, it, test } from "vitest";
 
-import * as xy from "@/spatial/xy/xy";
+import { location } from "@/spatial/location";
+import { xy } from "@/spatial/xy";
 
 describe("XY", () => {
   describe("construction", () => {
@@ -63,6 +64,44 @@ describe("XY", () => {
     expect(p.y).toEqual(9);
   });
 
+  describe("translate with Direction", () => {
+    it("should translate in the x direction", () => {
+      const p = xy.construct([1, 2]);
+      const result = xy.translate(p, "x", 5);
+      expect(result.x).toEqual(6);
+      expect(result.y).toEqual(2);
+    });
+
+    it("should translate in the y direction", () => {
+      const p = xy.construct([1, 2]);
+      const result = xy.translate(p, "y", 3);
+      expect(result.x).toEqual(1);
+      expect(result.y).toEqual(5);
+    });
+
+    it("should translate negative values in x direction", () => {
+      const p = xy.construct([10, 20]);
+      const result = xy.translate(p, "x", -7);
+      expect(result.x).toEqual(3);
+      expect(result.y).toEqual(20);
+    });
+
+    it("should translate negative values in y direction", () => {
+      const p = xy.construct([10, 20]);
+      const result = xy.translate(p, "y", -15);
+      expect(result.x).toEqual(10);
+      expect(result.y).toEqual(5);
+    });
+
+    it("should work with different input formats", () => {
+      const couple = xy.translate([5, 5], "x", 10);
+      expect(couple).toEqual({ x: 15, y: 5 });
+
+      const dims = xy.translate({ width: 3, height: 4 }, "y", 6);
+      expect(dims).toEqual({ x: 3, y: 10 });
+    });
+  });
+
   describe("equals", () => {
     const TESTS: Array<[xy.Crude, xy.Crude, boolean]> = [
       [[1, 1], { x: 1, y: 1 }, true],
@@ -80,7 +119,7 @@ describe("XY", () => {
     });
     it("should retrun true if the two points are within the given threshold", () => {
       const p = xy.construct([1, 1]);
-      expect(xy.equals(p, [1.1, 1.1], 0.15)).toBe(true);
+      expect(xy.equals(p, [1.1, 1.1], 0.15)).toBeTruthy();
     });
   });
   test("couple", () => {
@@ -89,15 +128,15 @@ describe("XY", () => {
   });
   describe("isNan", () => {
     it("should return true if x or y is NaN", () => {
-      expect(xy.isNan(xy.construct([1, NaN]))).toBe(true);
-      expect(xy.isNan(xy.construct([NaN, 1]))).toBe(true);
+      expect(xy.isNan(xy.construct([1, NaN]))).toBeTruthy();
+      expect(xy.isNan(xy.construct([NaN, 1]))).toBeTruthy();
     });
   });
   describe("isFinite", () => {
     it("should return true if x or y is finite", () => {
-      expect(xy.isFinite(xy.construct([1, 2]))).toBe(true);
-      expect(xy.isFinite(xy.construct([Infinity, 2]))).toBe(false);
-      expect(xy.isFinite(xy.construct([1, Infinity]))).toBe(false);
+      expect(xy.isFinite(xy.construct([1, 2]))).toBeTruthy();
+      expect(xy.isFinite(xy.construct([Infinity, 2]))).toBeFalsy();
+      expect(xy.isFinite(xy.construct([1, Infinity]))).toBeFalsy();
     });
   });
   describe("distance", () => {
@@ -151,4 +190,82 @@ describe("XY", () => {
       expect(xy.swap({ width: 5, height: 6 })).toEqual({ x: 6, y: 5 });
     });
   });
+
+  describe("translate with location.XY", () => {
+    it("should translate with top-left location", () => {
+      const p = xy.construct([10, 10]);
+      const result = xy.translate(p, location.TOP_LEFT, [5, 5]);
+      expect(result).toEqual({ x: 5, y: 5 });
+    });
+
+    it("should translate with top-right location", () => {
+      const p = xy.construct([10, 10]);
+      const result = xy.translate(p, location.TOP_RIGHT, [5, 5]);
+      expect(result).toEqual({ x: 15, y: 5 });
+    });
+
+    it("should translate with bottom-left location", () => {
+      const p = xy.construct([10, 10]);
+      const result = xy.translate(p, location.BOTTOM_LEFT, [5, 5]);
+      expect(result).toEqual({ x: 5, y: 15 });
+    });
+
+    it("should translate with bottom-right location", () => {
+      const p = xy.construct([10, 10]);
+      const result = xy.translate(p, location.BOTTOM_RIGHT, [5, 5]);
+      expect(result).toEqual({ x: 15, y: 15 });
+    });
+
+    it("should handle center x locations", () => {
+      const p = xy.construct([10, 10]);
+      const result = xy.translate(p, location.TOP_CENTER, [5, 5]);
+      expect(result).toEqual({ x: 10, y: 5 });
+
+      const result2 = xy.translate(p, location.BOTTOM_CENTER, [5, 5]);
+      expect(result2).toEqual({ x: 10, y: 15 });
+    });
+
+    it("should handle center y locations", () => {
+      const p = xy.construct([10, 10]);
+      const result = xy.translate(p, location.CENTER_LEFT, [5, 5]);
+      expect(result).toEqual({ x: 5, y: 10 });
+
+      const result2 = xy.translate(p, location.CENTER_RIGHT, [5, 5]);
+      expect(result2).toEqual({ x: 15, y: 10 });
+    });
+
+    it("should handle center-center location", () => {
+      const p = xy.construct([10, 10]);
+      const result = xy.translate(p, location.CENTER, [5, 5]);
+      expect(result).toEqual({ x: 10, y: 10 });
+    });
+
+    it("should work with different coordinate input formats", () => {
+      const result1 = xy.translate([10, 10], { x: "left", y: "top" }, [5, 5]);
+      expect(result1).toEqual({ x: 5, y: 5 });
+
+      const result2 = xy.translate(
+        { width: 10, height: 10 },
+        { x: "right", y: "bottom" },
+        { width: 5, height: 5 },
+      );
+      expect(result2).toEqual({ x: 15, y: 15 });
+    });
+
+    it("should handle negative translations correctly", () => {
+      const p = xy.construct([10, 10]);
+      const result = xy.translate(p, location.TOP_LEFT, [-5, -5]);
+      expect(result).toEqual({ x: 15, y: 15 });
+
+      const result2 = xy.translate(p, location.BOTTOM_RIGHT, [-5, -5]);
+      expect(result2).toEqual({ x: 5, y: 5 });
+    });
+
+    it("should work with custom location objects", () => {
+      const p = xy.construct([10, 10]);
+      const customLocation: location.XY = { x: "left", y: "bottom" };
+      const result = xy.translate(p, customLocation, [3, 7]);
+      expect(result).toEqual({ x: 7, y: 17 });
+    });
+  });
 });

package/src/spatial/xy/xy.ts

@@ -20,6 +20,7 @@ import {
   type XY,
   xy,
 } from "@/spatial/base";
+import { type location } from "@/spatial/location";
 
 export { type ClientXY as Client, clientXY, type XY, xy };
 
@@ -109,15 +110,27 @@ interface Translate {
   (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 coordinates translated by the given amount. */
+  (a: Crude, direction: location.XY, xy: Crude): XY;
 }
 
 export const translate: Translate = (a, b, v, ...cb): XY => {
-  if (typeof b === "string" && typeof v === "number") {
+  if (typeof b === "string") {
+    if (typeof v !== "number") throw new Error("The value must be a number.");
     if (b === "x") return translateX(a, v);
     return translateY(a, v);
   }
+  if (typeof b === "object" && "x" in b && typeof b.x === "string") {
+    const amnt = construct(v);
+    const root = construct(a);
+    if (b.x === "left") amnt.x = -amnt.x;
+    else if (b.x === "center") amnt.x = 0;
+    if (b.y === "top") amnt.y = -amnt.y;
+    else if (b.y === "center") amnt.y = 0;
+    return { x: root.x + amnt.x, y: root.y + amnt.y };
+  }
   return [a, b, v ?? ZERO, ...cb].reduce((p: XY, c) => {
-    const xy = construct(c as Crude);
+    const xy = construct(c);
     return { x: p.x + xy.x, y: p.y + xy.y };
   }, ZERO);
 };

package/src/status/status.ts

@@ -89,3 +89,14 @@ export const create = <D = undefined, V extends Variant = Variant>(
     time: TimeStamp.now(),
     ...spec,
   }) as unknown as Status<D, V>;
+
+export const filterVariant = (
+  variant: Variant,
+  only: Variant | Variant[] = [],
+): Variant | undefined => {
+  if (Array.isArray(only)) {
+    if (only.includes(variant)) return variant;
+    return undefined;
+  }
+  return only === variant ? variant : undefined;
+};

package/src/strings/strings.spec.ts

@@ -15,6 +15,9 @@ describe("naturalLanguageJoin", () => {
   it("should return an empty string for an empty array", () =>
     expect(strings.naturalLanguageJoin([])).toBe(""));
 
+  it("should return the string for a single string", () =>
+    expect(strings.naturalLanguageJoin("apple")).toBe("apple"));
+
   it("should return the zeroLength string for an empty array if provided", () =>
     expect(strings.naturalLanguageJoin([], "No items")).toBe("No items"));
 

package/src/strings/strings.ts

@@ -24,9 +24,10 @@
  * ```
  */
 export const naturalLanguageJoin = (
-  strings: string[],
+  strings: string | string[],
   zeroLength: string = "",
 ): string => {
+  if (typeof strings === "string") return strings;
   const length = strings.length;
   if (length === 0) return zeroLength;
   if (length === 1) return strings[0];