Add programmatic creation support for MSDL Environment elements (#104)

* Initial plan

* Initial analysis of Environment element support

Co-authored-by: kjellmf <[email protected]>

* Add Environment.create() and areaOfInterest setter with comprehensive tests

Co-authored-by: kjellmf <[email protected]>

* Add changeset for Environment creation support

Co-authored-by: kjellmf <[email protected]>

* Format changeset file so that CI passes

* Refactor Environment.create() to use createEmptyXMLElementFromTagName for XML element creation

* Add RectangleArea.fromModel method with validation and tests

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: kjellmf <[email protected]>
Co-authored-by: kmf <[email protected]>

Author: Copilot

.changeset/environment-creation-support.md

@@ -0,0 +1,9 @@
+---
+"@orbat-mapper/msdllib": minor
+---
+
+Add programmatic creation support for Environment elements. This includes:
+
+- `Environment.create()` static factory method for creating new Environment elements
+- `areaOfInterest` getter and setter for programmatic manipulation of AreaOfInterest
+- `RectangleArea.create()` static factory method for creating RectangleArea elements with coordinate cloning

package-lock.json

@@ -3,6 +3,7 @@ import {
   getValueOrUndefined,
   removeUndefinedValues,
   setOrCreateTagValue,
+  createEmptyXMLElementFromTagName,
 } from "./domutils.js";
 import { MsdlCoordinates } from "./geo.js";
 import type { BBox, Feature, Polygon } from "geojson";
@@ -29,16 +30,16 @@ export interface RectangleAreaType {
 export class Environment implements EnvironmentType {
   static readonly TAG_NAME = "Environment";
   element: Element;
-  areaOfInterest?: RectangleArea;
+  #areaOfInterest?: RectangleArea;
   #scenarioTime?: string;
   constructor(element: Element) {
     this.element = element;
     this.#scenarioTime = getValueOrUndefined(element, "ScenarioTime");
     const areaOfInterestElement = getTagElement(element, "AreaOfInterest");
     if (areaOfInterestElement) {
-      this.areaOfInterest = new RectangleArea(areaOfInterestElement);
+      this.#areaOfInterest = new RectangleArea(areaOfInterestElement);
     } else {
-      this.areaOfInterest = undefined;
+      this.#areaOfInterest = undefined;
     }
   }
 
@@ -53,12 +54,37 @@ export class Environment implements EnvironmentType {
     setOrCreateTagValue(this.element, "ScenarioTime", value);
   }
 
+  get areaOfInterest(): RectangleArea | undefined {
+    if (this.#areaOfInterest) return this.#areaOfInterest;
+    const areaOfInterestElement = getTagElement(this.element, "AreaOfInterest");
+    if (areaOfInterestElement) {
+      this.#areaOfInterest = new RectangleArea(areaOfInterestElement);
+    }
+    return this.#areaOfInterest;
+  }
+
+  set areaOfInterest(value: RectangleArea | undefined) {
+    this.#areaOfInterest = value;
+    const existingElement = getTagElement(this.element, "AreaOfInterest");
+    if (existingElement) {
+      this.element.removeChild(existingElement);
+    }
+    if (value) {
+      this.element.appendChild(value.element);
+    }
+  }
+
   toObject(): EnvironmentType {
     return removeUndefinedValues({
       scenarioTime: this.scenarioTime,
       areaOfInterest: this.areaOfInterest?.toObject(),
     }) as EnvironmentType;
   }
+
+  static create(): Environment {
+    const element = createEmptyXMLElementFromTagName(Environment.TAG_NAME);
+    return new Environment(element);
+  }
 }
 
 export class RectangleArea {
@@ -124,4 +150,39 @@ export class RectangleArea {
       bboxPolygon(bbox, { properties: { name: this.name } }),
     );
   }
+
+  static create(
+    upperRight: MsdlCoordinates,
+    lowerLeft: MsdlCoordinates,
+  ): RectangleArea {
+    const element = createEmptyXMLElementFromTagName("AreaOfInterest");
+
+    // Clone coordinates with proper tag names
+    const upperRightClone = MsdlCoordinates.create(
+      upperRight.coordinateChoice,
+      "UpperRight",
+    );
+    upperRightClone.location = upperRight.location;
+
+    const lowerLeftClone = MsdlCoordinates.create(
+      lowerLeft.coordinateChoice,
+      "LowerLeft",
+    );
+    lowerLeftClone.location = lowerLeft.location;
+
+    element.appendChild(upperRightClone.element);
+    element.appendChild(lowerLeftClone.element);
+    return new RectangleArea(element);
+  }
+
+  static fromModel(model: RectangleAreaType): RectangleArea {
+    if (!model.upperRight || !model.lowerLeft) {
+      throw new Error("Both upperRight and lowerLeft coordinates are required");
+    }
+    const area = RectangleArea.create(model.upperRight, model.lowerLeft);
+    if (model.name) {
+      area.name = model.name;
+    }
+    return area;
+  }
 }

src/lib/environment.ts

@@ -154,3 +154,129 @@ describe("MilitaryScenario Environment", () => {
     expect(scenario.environment?.scenarioTime).toBe("2025-07-09T11:11:00Z");
   });
 });
+
+describe("Environment creation", () => {
+  it("should create an empty Environment using create()", () => {
+    const environment = Environment.create();
+    expect(environment).toBeInstanceOf(Environment);
+    expect(environment.element).toBeInstanceOf(Element);
+    expect(environment.scenarioTime).toBeUndefined();
+    expect(environment.areaOfInterest).toBeUndefined();
+  });
+
+  it("should allow setting scenarioTime programmatically", () => {
+    const environment = Environment.create();
+    environment.scenarioTime = "2025-12-31T23:59:59Z";
+    expect(environment.scenarioTime).toBe("2025-12-31T23:59:59Z");
+    expect(environment.element.outerHTML).toContain(
+      "<ScenarioTime>2025-12-31T23:59:59Z</ScenarioTime>",
+    );
+  });
+
+  it("should allow setting areaOfInterest programmatically", () => {
+    const environment = Environment.create();
+    const upperRight = MsdlCoordinates.createGDCLocation([10, 20, 0]);
+    const lowerLeft = MsdlCoordinates.createGDCLocation([5, 15, 0]);
+    const rectangleArea = RectangleArea.create(upperRight, lowerLeft);
+    rectangleArea.name = "Test Area";
+
+    environment.areaOfInterest = rectangleArea;
+
+    expect(environment.areaOfInterest).toBeInstanceOf(RectangleArea);
+    expect(environment.areaOfInterest?.name).toBe("Test Area");
+    expect(environment.element.outerHTML).toContain("<AreaOfInterest>");
+  });
+
+  it("should allow removing areaOfInterest", () => {
+    const environment = new Environment(
+      parseFromString(ENVIRONMENT_SAMPLE_MGRS),
+    );
+    expect(environment.areaOfInterest).toBeInstanceOf(RectangleArea);
+
+    environment.areaOfInterest = undefined;
+    expect(environment.areaOfInterest).toBeUndefined();
+    expect(environment.element.outerHTML).not.toContain("<AreaOfInterest>");
+  });
+});
+
+describe("RectangleArea creation", () => {
+  it("should create a RectangleArea using create()", () => {
+    const upperRight = MsdlCoordinates.createGDCLocation([10, 20, 0]);
+    const lowerLeft = MsdlCoordinates.createGDCLocation([5, 15, 0]);
+    const rectangleArea = RectangleArea.create(upperRight, lowerLeft);
+
+    expect(rectangleArea).toBeInstanceOf(RectangleArea);
+    expect(rectangleArea.upperRight).toBeInstanceOf(MsdlCoordinates);
+    expect(rectangleArea.lowerLeft).toBeInstanceOf(MsdlCoordinates);
+  });
+
+  it("should allow setting name on created RectangleArea", () => {
+    const upperRight = MsdlCoordinates.createGDCLocation([10, 20, 0]);
+    const lowerLeft = MsdlCoordinates.createGDCLocation([5, 15, 0]);
+    const rectangleArea = RectangleArea.create(upperRight, lowerLeft);
+
+    rectangleArea.name = "My Area";
+    expect(rectangleArea.name).toBe("My Area");
+    expect(rectangleArea.element.outerHTML).toContain("<Name>My Area</Name>");
+  });
+
+  it("should compute correct bounding box for created RectangleArea", () => {
+    const upperRight = MsdlCoordinates.createGDCLocation([10, 20, 0]);
+    const lowerLeft = MsdlCoordinates.createGDCLocation([5, 15, 0]);
+    const rectangleArea = RectangleArea.create(upperRight, lowerLeft);
+
+    const bbox = rectangleArea.toBoundingBox();
+    expect(bbox).toBeDefined();
+    expect(bbox).toHaveLength(4);
+    expect(bbox![0]).toBeCloseTo(5, 5);
+    expect(bbox![1]).toBeCloseTo(15, 5);
+    expect(bbox![2]).toBeCloseTo(10, 5);
+    expect(bbox![3]).toBeCloseTo(20, 5);
+  });
+});
+
+describe("RectangleArea.fromModel", () => {
+  it("should create a RectangleArea from a valid model object", () => {
+    const upperRight = MsdlCoordinates.createGDCLocation([10, 20, 0]);
+    const lowerLeft = MsdlCoordinates.createGDCLocation([5, 15, 0]);
+    const model = {
+      name: "Test AOI",
+      upperRight,
+      lowerLeft,
+    };
+    const area = RectangleArea.fromModel(model);
+    expect(area).toBeInstanceOf(RectangleArea);
+    expect(area.name).toBe("Test AOI");
+    expect(area.upperRight.location).toEqual([10, 20, 0]);
+    expect(area.lowerLeft.location).toEqual([5, 15, 0]);
+  });
+
+  it("should throw if upperRight is missing", () => {
+    const lowerLeft = MsdlCoordinates.createGDCLocation([5, 15, 0]);
+    const model = {
+      name: "Test AOI",
+      lowerLeft,
+    };
+    expect(() => RectangleArea.fromModel(model as any)).toThrow();
+  });
+
+  it("should throw if lowerLeft is missing", () => {
+    const upperRight = MsdlCoordinates.createGDCLocation([10, 20, 0]);
+    const model = {
+      name: "Test AOI",
+      upperRight,
+    };
+    expect(() => RectangleArea.fromModel(model as any)).toThrow();
+  });
+
+  it("should set name to undefined if not provided", () => {
+    const upperRight = MsdlCoordinates.createGDCLocation([10, 20, 0]);
+    const lowerLeft = MsdlCoordinates.createGDCLocation([5, 15, 0]);
+    const model = {
+      upperRight,
+      lowerLeft,
+    };
+    const area = RectangleArea.fromModel(model);
+    expect(area.name).toBeUndefined();
+  });
+});