midgard-hex-grid 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Niklas Herrloff
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,208 @@
-# Temporary Holding Version
+# Midgard Hex Grid
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Midgard Hex Grid is a small reusable TypeScript library for creating and working with hexagonal grids.
+
+The library supports both x-dominated and y-dominated hex grids and handles the coordinate system, neighbour calculations, positioning and hexagon geometry. Its purpose is to let another programmer work with hexagonal grids without having to implement these calculations themselves.
+
+## Features
+
+- Create x-dominated and y-dominated hex grids
+- Create a single hexagon
+- Generate complete grids from a rectangular skeleton
+- Calculate the six neighbours of a coordinate
+- Validate Midgard coordinates
+- Calculate center positions
+- Calculate the six corner points of a hexagon
+- Calculate the outer bounds of a grid
+- Generate coordinate ranges
+- Generate layered coordinates with z-index values for rendering
+
+## Requirements
+
+- TypeScript
+- JavaScript environment with ES modules
+
+The library has no runtime dependencies.
+
+Development uses:
+
+- TypeScript 7
+- Vitest 5
+
+## Installation
+
+Clone the repository and install the development dependencies:
+
+```bash
+npm install
+```
+
+Build the library:
+
+```bash
+npm run build
+```
+
+The compiled JavaScript and TypeScript declarations are generated in the `dist` directory.
+
+## Basic usage
+
+The main class is `HexGrid`.
+
+Create a grid by first choosing its orientation:
+
+```ts
+import { HexGrid } from './dist/index.js'
+
+const grid = new HexGrid('x-dominated')
+```
+
+The orientation can be:
+
+```ts
+'x-dominated'
+```
+
+or:
+
+```ts
+'y-dominated'
+```
+
+### Create a single hexagon
+
+```ts
+const grid = new HexGrid('x-dominated')
+
+const hexagon = grid.createSingleHexagon({
+  hexDiameter: 100
+})
+```
+
+The returned hexagon contains:
+
+- its Midgard coordinate
+- its center position
+- its six corner points
+
+These values can, for example, be used by an application to render the hexagon as SVG.
+
+### Create a complete grid
+
+```ts
+const grid = new HexGrid('x-dominated')
+
+const hexagons = grid.createGrid({
+  hexDiameter: 100,
+  skeletonWidth: 3,
+  skeletonHeight: 2
+})
+```
+
+`skeletonWidth` and `skeletonHeight` describe the rectangular skeleton around which the complete grid is generated.
+
+The library automatically fills the surrounding coordinates and returns the hexagons in rendering order with calculated z-index values.
+
+### Y-dominated grid
+
+The same API can be used for the other orientation:
+
+```ts
+const grid = new HexGrid('y-dominated')
+
+const hexagons = grid.createGrid({
+  hexDiameter: 100,
+  skeletonWidth: 3,
+  skeletonHeight: 2
+})
+```
+
+The grid orientation controls the coordinate relationships, positioning and geometry internally.
+
+## Neighbours
+
+The six neighbouring coordinates can be calculated through the grid:
+
+```ts
+const neighbours = grid.getNeighbours({
+  x: 2,
+  y: 2
+})
+```
+
+The result depends on whether the `HexGrid` is x-dominated or y-dominated.
+
+## Coordinate validation
+
+A coordinate can be checked before it is used:
+
+```ts
+const valid = grid.isValidCoordinate({
+  x: 2,
+  y: 2
+})
+```
+
+## Lower-level API
+
+`HexGrid` provides the simplest interface for most uses.
+
+The library also exports lower-level classes for programmers who want to work directly with individual parts of the grid system, including:
+
+- `CoordinateValidator`
+- `NeighbourCalculator`
+- `HexagonGeometry`
+- `CoordinatePositioner`
+- `CoordinateRange`
+- `CoordinateRangeFiller`
+- `CoordinateLayer`
+
+The public TypeScript types are exported from `src/index.ts`.
+
+## Testing
+
+The mathematical and coordinate logic is tested with automated unit tests using Vitest.
+
+Run all automated tests with:
+
+```bash
+npx vitest run
+```
+
+The library is also tested visually with a separate graphical Test-App. This makes it possible to verify that the calculated coordinates and geometry produce the expected SVG hexagons and grid layouts.
+
+See [`TEST_REPORT.md`](./TEST_REPORT.md) for the test documentation and results.
+
+## Development commands
+
+Check the TypeScript code without producing build files:
+
+```bash
+npm run check
+```
+
+Build the library:
+
+```bash
+npm run build
+```
+
+Run the automated tests:
+
+```bash
+npx vitest run
+```
+
+## Version
+
+Current version: `1.0.0`
+
+The version is also available from the library:
+
+```ts
+import { MIDGARD_HEX_GRID_VERSION } from './dist/index.js'
+```
+
+## License
+
+ISC

package/dist/c-r-fill-around.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Determines whether a Midgard coordinate range
+ * should be filled around its skeleton.
+ */
+export declare class CoordinateRangeFillAround {
+    /**
+     * Determines whether surrounding coordinates should be added.
+     *
+     * A 1 by 1 skeleton can choose whether to use fillAround.
+     * Any larger skeleton is always filled around automatically.
+     *
+     * @param width - The width of the coordinate range.
+     * @param height - The height of the coordinate range.
+     * @param fillAround - Whether a 1 by 1 range should be filled around.
+     * @returns True if the range should be filled around.
+     */
+    shouldFillAround(width: number, height: number, fillAround?: boolean): boolean;
+}
+//# sourceMappingURL=c-r-fill-around.d.ts.map

package/dist/c-r-fill-around.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"c-r-fill-around.d.ts","sourceRoot":"","sources":["../src/c-r-fill-around.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,yBAAyB;IAClC;;;;;;;;;;OAUG;IACH,gBAAgB,CACd,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,OAAe,GAC1B,OAAO,CAaT;CACF"}

package/dist/c-r-fill-around.js

@@ -0,0 +1,28 @@
+/**
+ * Determines whether a Midgard coordinate range
+ * should be filled around its skeleton.
+ */
+export class CoordinateRangeFillAround {
+    /**
+     * Determines whether surrounding coordinates should be added.
+     *
+     * A 1 by 1 skeleton can choose whether to use fillAround.
+     * Any larger skeleton is always filled around automatically.
+     *
+     * @param width - The width of the coordinate range.
+     * @param height - The height of the coordinate range.
+     * @param fillAround - Whether a 1 by 1 range should be filled around.
+     * @returns True if the range should be filled around.
+     */
+    shouldFillAround(width, height, fillAround = false) {
+        const isSingleCoordinate = width === 1 && height === 1;
+        if (!isSingleCoordinate) {
+            return true;
+        }
+        if (fillAround) {
+            return true;
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=c-r-fill-around.js.map

package/dist/c-r-fill-around.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"c-r-fill-around.js","sourceRoot":"","sources":["../src/c-r-fill-around.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,yBAAyB;IAClC;;;;;;;;;;OAUG;IACH,gBAAgB,CACd,KAAa,EACb,MAAc,EACd,UAAU,GAAY,KAAK;QAE3B,MAAM,kBAAkB,GACtB,KAAK,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,CAAA;QAE7B,IAAI,CAAC,kBAAkB,EAAE,CAAC;YACxB,OAAO,IAAI,CAAA;QACb,CAAC;QAED,IAAI,UAAU,EAAE,CAAC;YACf,OAAO,IAAI,CAAA;QACb,CAAC;QAED,OAAO,KAAK,CAAA;IACd,CAAC;CACF"}

package/dist/c-r-skeleton.d.ts

@@ -0,0 +1,18 @@
+import type { Coordinate } from './coordinate.js';
+/**
+ * Creates the skeleton coordinates for a Midgard coordinate range.
+ *
+ * The upper-left skeleton coordinate is always (2, 2).
+ * Skeleton coordinates use steps of two in both directions.
+ */
+export declare class CoordinateRangeSkeleton {
+    /**
+     * Creates a rectangular skeleton of coordinates.
+     *
+     * @param width - The number of skeleton coordinates horizontally.
+     * @param height - The number of skeleton coordinates vertically.
+     * @returns The coordinates that form the skeleton.
+     */
+    create(width: number, height: number): Coordinate[];
+}
+//# sourceMappingURL=c-r-skeleton.d.ts.map

package/dist/c-r-skeleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"c-r-skeleton.d.ts","sourceRoot":"","sources":["../src/c-r-skeleton.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD;;;;;GAKG;AACH,qBAAa,uBAAuB;IAClC;;;;;;OAMG;IACH,MAAM,CACJ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,UAAU,EAAE,CAoBd;CACF"}

package/dist/c-r-skeleton.js

@@ -0,0 +1,32 @@
+/**
+ * Creates the skeleton coordinates for a Midgard coordinate range.
+ *
+ * The upper-left skeleton coordinate is always (2, 2).
+ * Skeleton coordinates use steps of two in both directions.
+ */
+export class CoordinateRangeSkeleton {
+    /**
+     * Creates a rectangular skeleton of coordinates.
+     *
+     * @param width - The number of skeleton coordinates horizontally.
+     * @param height - The number of skeleton coordinates vertically.
+     * @returns The coordinates that form the skeleton.
+     */
+    create(width, height) {
+        const coordinates = [];
+        const startX = 2;
+        const startY = 2;
+        for (let yIndex = 0; yIndex < height; yIndex++) {
+            const y = startY + yIndex * 2;
+            for (let xIndex = 0; xIndex < width; xIndex++) {
+                const x = startX + xIndex * 2;
+                coordinates.push({
+                    x,
+                    y
+                });
+            }
+        }
+        return coordinates;
+    }
+}
+//# sourceMappingURL=c-r-skeleton.js.map

package/dist/c-r-skeleton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"c-r-skeleton.js","sourceRoot":"","sources":["../src/c-r-skeleton.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,OAAO,uBAAuB;IAClC;;;;;;OAMG;IACH,MAAM,CACJ,KAAa,EACb,MAAc;QAEd,MAAM,WAAW,GAAiB,EAAE,CAAA;QAEpC,MAAM,MAAM,GAAG,CAAC,CAAA;QAChB,MAAM,MAAM,GAAG,CAAC,CAAA;QAEhB,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;YAC/C,MAAM,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,CAAC,CAAA;YAE7B,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;gBAC9C,MAAM,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,CAAC,CAAA;gBAE7B,WAAW,CAAC,IAAI,CAAC;oBACf,CAAC;oBACD,CAAC;iBACF,CAAC,CAAA;YACJ,CAAC;QACH,CAAC;QAED,OAAO,WAAW,CAAA;IACpB,CAAC;CACF"}

package/dist/c-r-validation.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Validates the dimensions of a Midgard coordinate range.
+ */
+export declare class CoordinateRangeValidator {
+    /**
+     * Checks whether width and height are valid range dimensions.
+     *
+     * Both dimensions must be positive integers.
+     *
+     * @param width - The width of the coordinate range.
+     * @param height - The height of the coordinate range.
+     * @returns True if both dimensions are valid.
+     */
+    isValid(width: number, height: number): boolean;
+}
+//# sourceMappingURL=c-r-validation.d.ts.map

package/dist/c-r-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"c-r-validation.d.ts","sourceRoot":"","sources":["../src/c-r-validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,wBAAwB;IACjC;;;;;;;;OAQG;IACH,OAAO,CACL,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAkBT;CACF"}

package/dist/c-r-validation.js

@@ -0,0 +1,30 @@
+/**
+ * Validates the dimensions of a Midgard coordinate range.
+ */
+export class CoordinateRangeValidator {
+    /**
+     * Checks whether width and height are valid range dimensions.
+     *
+     * Both dimensions must be positive integers.
+     *
+     * @param width - The width of the coordinate range.
+     * @param height - The height of the coordinate range.
+     * @returns True if both dimensions are valid.
+     */
+    isValid(width, height) {
+        if (!Number.isInteger(width)) {
+            return false;
+        }
+        if (!Number.isInteger(height)) {
+            return false;
+        }
+        if (width < 1) {
+            return false;
+        }
+        if (height < 1) {
+            return false;
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=c-r-validation.js.map

package/dist/c-r-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"c-r-validation.js","sourceRoot":"","sources":["../src/c-r-validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,wBAAwB;IACjC;;;;;;;;OAQG;IACH,OAAO,CACL,KAAa,EACb,MAAc;QAEd,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,OAAO,KAAK,CAAA;QACd,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAA;QACd,CAAC;QAED,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACd,OAAO,KAAK,CAAA;QACd,CAAC;QAED,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YACf,OAAO,KAAK,CAAA;QACd,CAAC;QAED,OAAO,IAAI,CAAA;IACb,CAAC;CACF"}

package/dist/coordinate-layer.d.ts

@@ -0,0 +1,52 @@
+import type { Coordinate } from './coordinate.js';
+/**
+ * Represents a Midgard coordinate with a z-index for rendering.
+ *
+ * The z-index is based on the coordinate's y row.
+ * The row with the lowest y value starts at 100,
+ * and each following row increases by 100.
+ */
+export type LayeredCoordinate = {
+    x: number;
+    y: number;
+    zIndex: number;
+};
+/**
+ * Handles sorting and layering of Midgard coordinates
+ * for rendering.
+ */
+export declare class CoordinateLayer {
+    private readonly coordinates;
+    /**
+     * Creates a new coordinate layer.
+     *
+     * A copy of the coordinates is stored so that the original
+     * array is not changed.
+     *
+     * @param coordinates - The coordinates to sort and layer.
+     */
+    constructor(coordinates: Coordinate[]);
+    /**
+     * Sorts the coordinates by y first and x second.
+     *
+     * Coordinates with the lowest y value come first.
+     * Coordinates on the same y row are ordered from
+     * the lowest x value to the highest x value.
+     *
+     * @returns A new array containing the sorted coordinates.
+     */
+    sortCoordinates(): Coordinate[];
+    /**
+     * Creates layered coordinates for rendering a Midgard hex grid.
+     *
+     * Coordinates are ordered by y first and x second.
+     * The first y row receives z-index 100.
+     * Each following y row increases the z-index by 100.
+     *
+     * All coordinates on the same y row receive the same z-index.
+     *
+     * @returns Sorted coordinates with their calculated z-index.
+     */
+    getLayeredCoordinates(): LayeredCoordinate[];
+}
+//# sourceMappingURL=coordinate-layer.d.ts.map

package/dist/coordinate-layer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinate-layer.d.ts","sourceRoot":"","sources":["../src/coordinate-layer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAED;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAE1C;;;;;;;OAOG;IACH,YAAY,WAAW,EAAE,UAAU,EAAE,EAEpC;IAED;;;;;;;;OAQG;IACH,eAAe,IAAI,UAAU,EAAE,CAY9B;IAED;;;;;;;;;;OAUG;IACH,qBAAqB,IAAI,iBAAiB,EAAE,CAqB3C;CACF"}

package/dist/coordinate-layer.js

@@ -0,0 +1,67 @@
+/**
+ * Handles sorting and layering of Midgard coordinates
+ * for rendering.
+ */
+export class CoordinateLayer {
+    coordinates;
+    /**
+     * Creates a new coordinate layer.
+     *
+     * A copy of the coordinates is stored so that the original
+     * array is not changed.
+     *
+     * @param coordinates - The coordinates to sort and layer.
+     */
+    constructor(coordinates) {
+        this.coordinates = [...coordinates];
+    }
+    /**
+     * Sorts the coordinates by y first and x second.
+     *
+     * Coordinates with the lowest y value come first.
+     * Coordinates on the same y row are ordered from
+     * the lowest x value to the highest x value.
+     *
+     * @returns A new array containing the sorted coordinates.
+     */
+    sortCoordinates() {
+        const sortedCoordinates = [...this.coordinates];
+        sortedCoordinates.sort((firstCoordinate, secondCoordinate) => {
+            if (firstCoordinate.y !== secondCoordinate.y) {
+                return firstCoordinate.y - secondCoordinate.y;
+            }
+            return firstCoordinate.x - secondCoordinate.x;
+        });
+        return sortedCoordinates;
+    }
+    /**
+     * Creates layered coordinates for rendering a Midgard hex grid.
+     *
+     * Coordinates are ordered by y first and x second.
+     * The first y row receives z-index 100.
+     * Each following y row increases the z-index by 100.
+     *
+     * All coordinates on the same y row receive the same z-index.
+     *
+     * @returns Sorted coordinates with their calculated z-index.
+     */
+    getLayeredCoordinates() {
+        const sortedCoordinates = this.sortCoordinates();
+        const layeredCoordinates = [];
+        let previousY;
+        let zIndex = 0;
+        for (const coordinate of sortedCoordinates) {
+            if (coordinate.y !== previousY) {
+                zIndex += 100;
+                previousY = coordinate.y;
+            }
+            layeredCoordinates.push({
+                x: coordinate.x,
+                y: coordinate.y,
+                zIndex
+            });
+        }
+        return layeredCoordinates;
+    }
+}
+//# sourceMappingURL=coordinate-layer.js.map

package/dist/coordinate-layer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinate-layer.js","sourceRoot":"","sources":["../src/coordinate-layer.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,MAAM,OAAO,eAAe;IACT,WAAW,CAAc;IAE1C;;;;;;;OAOG;IACH,YAAY,WAAyB;QACnC,IAAI,CAAC,WAAW,GAAG,CAAC,GAAG,WAAW,CAAC,CAAA;IACrC,CAAC;IAED;;;;;;;;OAQG;IACH,eAAe;QACb,MAAM,iBAAiB,GAAG,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,CAAA;QAE/C,iBAAiB,CAAC,IAAI,CAAC,CAAC,eAAe,EAAE,gBAAgB,EAAE,EAAE;YAC3D,IAAI,eAAe,CAAC,CAAC,KAAK,gBAAgB,CAAC,CAAC,EAAE,CAAC;gBAC7C,OAAO,eAAe,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAA;YAC/C,CAAC;YAED,OAAO,eAAe,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAA;QAC/C,CAAC,CAAC,CAAA;QAEF,OAAO,iBAAiB,CAAA;IAC1B,CAAC;IAED;;;;;;;;;;OAUG;IACH,qBAAqB;QACnB,MAAM,iBAAiB,GAAG,IAAI,CAAC,eAAe,EAAE,CAAA;QAChD,MAAM,kBAAkB,GAAwB,EAAE,CAAA;QAElD,IAAI,SAA6B,CAAA;QACjC,IAAI,MAAM,GAAG,CAAC,CAAA;QAEd,KAAK,MAAM,UAAU,IAAI,iBAAiB,EAAE,CAAC;YAC3C,IAAI,UAAU,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;gBAC/B,MAAM,IAAI,GAAG,CAAA;gBACb,SAAS,GAAG,UAAU,CAAC,CAAC,CAAA;YAC1B,CAAC;YAED,kBAAkB,CAAC,IAAI,CAAC;gBACtB,CAAC,EAAE,UAAU,CAAC,CAAC;gBACf,CAAC,EAAE,UAAU,CAAC,CAAC;gBACf,MAAM;aACP,CAAC,CAAA;QACJ,CAAC;QAED,OAAO,kBAAkB,CAAA;IAC3B,CAAC;CACF"}

package/dist/coordinate-positioner.d.ts

@@ -0,0 +1,49 @@
+import type { Coordinate } from './coordinate.js';
+import type { Point } from './geometry.js';
+import type { GridOrientation } from './orientation.js';
+/**
+ * Converts Midgard grid coordinates into geometric center positions.
+ *
+ * The calculated point represents the center of a hexagon
+ * in a two-dimensional coordinate system such as SVG.
+ */
+export declare class CoordinatePositioner {
+    private readonly orientation;
+    /**
+     * Creates a new coordinate positioner.
+     *
+     * @param orientation - The orientation of the hex grid.
+     */
+    constructor(orientation: GridOrientation);
+    /**
+     * Calculates the center position of a Midgard coordinate.
+     *
+     * For an x-dominated grid, dimension represents the
+     * complete width of one hexagon.
+     *
+     * For a y-dominated grid, dimension represents the
+     * complete height of one hexagon.
+     *
+     * @param coordinate - The Midgard coordinate to position.
+     * @param dimension - The width or height of one hexagon.
+     * @returns The calculated center point.
+     */
+    getCenterPosition(coordinate: Coordinate, dimension: number): Point;
+    /**
+     * Calculates the center position in an x-dominated grid.
+     *
+     * @param coordinate - The Midgard coordinate to position.
+     * @param width - The complete width of one hexagon.
+     * @returns The calculated center point.
+     */
+    getXDominatedCenterPosition(coordinate: Coordinate, width: number): Point;
+    /**
+     * Calculates the center position in a y-dominated grid.
+     *
+     * @param coordinate - The Midgard coordinate to position.
+     * @param height - The complete height of one hexagon.
+     * @returns The calculated center point.
+     */
+    getYDominatedCenterPosition(coordinate: Coordinate, height: number): Point;
+}
+//# sourceMappingURL=coordinate-positioner.d.ts.map

package/dist/coordinate-positioner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinate-positioner.d.ts","sourceRoot":"","sources":["../src/coordinate-positioner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAE1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAEvD;;;;;GAKG;AACH,qBAAa,oBAAoB;IAE/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiB;IAE7C;;;;OAIG;IACH,YAAY,WAAW,EAAE,eAAe,EAIvC;IAED;;;;;;;;;;;;OAYG;IACI,iBAAiB,CACtB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,MAAM,GAChB,KAAK,CAgBP;IAED;;;;;;OAMG;IACI,2BAA2B,CAChC,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,MAAM,GACZ,KAAK,CAeP;IAED;;;;;;OAMG;IACI,2BAA2B,CAChC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,MAAM,GACb,KAAK,CAeP;CAEF"}

package/dist/coordinate-positioner.js

@@ -0,0 +1,69 @@
+/**
+ * Converts Midgard grid coordinates into geometric center positions.
+ *
+ * The calculated point represents the center of a hexagon
+ * in a two-dimensional coordinate system such as SVG.
+ */
+export class CoordinatePositioner {
+    orientation;
+    /**
+     * Creates a new coordinate positioner.
+     *
+     * @param orientation - The orientation of the hex grid.
+     */
+    constructor(orientation) {
+        this.orientation = orientation;
+    }
+    /**
+     * Calculates the center position of a Midgard coordinate.
+     *
+     * For an x-dominated grid, dimension represents the
+     * complete width of one hexagon.
+     *
+     * For a y-dominated grid, dimension represents the
+     * complete height of one hexagon.
+     *
+     * @param coordinate - The Midgard coordinate to position.
+     * @param dimension - The width or height of one hexagon.
+     * @returns The calculated center point.
+     */
+    getCenterPosition(coordinate, dimension) {
+        if (this.orientation === 'x-dominated') {
+            return this.getXDominatedCenterPosition(coordinate, dimension);
+        }
+        return this.getYDominatedCenterPosition(coordinate, dimension);
+    }
+    /**
+     * Calculates the center position in an x-dominated grid.
+     *
+     * @param coordinate - The Midgard coordinate to position.
+     * @param width - The complete width of one hexagon.
+     * @returns The calculated center point.
+     */
+    getXDominatedCenterPosition(coordinate, width) {
+        const hexagonHeight = (width * 2) / Math.sqrt(3);
+        const xStep = width / 2;
+        const yStep = (hexagonHeight * 3) / 4;
+        return {
+            x: coordinate.x * xStep,
+            y: coordinate.y * yStep
+        };
+    }
+    /**
+     * Calculates the center position in a y-dominated grid.
+     *
+     * @param coordinate - The Midgard coordinate to position.
+     * @param height - The complete height of one hexagon.
+     * @returns The calculated center point.
+     */
+    getYDominatedCenterPosition(coordinate, height) {
+        const hexagonWidth = (height * 2) / Math.sqrt(3);
+        const xStep = (hexagonWidth * 3) / 4;
+        const yStep = height / 2;
+        return {
+            x: coordinate.x * xStep,
+            y: coordinate.y * yStep
+        };
+    }
+}
+//# sourceMappingURL=coordinate-positioner.js.map

package/dist/coordinate-positioner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinate-positioner.js","sourceRoot":"","sources":["../src/coordinate-positioner.ts"],"names":[],"mappings":"AAMA;;;;;GAKG;AACH,MAAM,OAAO,oBAAoB;IAEd,WAAW,CAAiB;IAE7C;;;;OAIG;IACH,YAAY,WAA4B;QAEtC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAA;IAEhC,CAAC;IAED;;;;;;;;;;;;OAYG;IACI,iBAAiB,CACtB,UAAsB,EACtB,SAAiB;QAGjB,IAAI,IAAI,CAAC,WAAW,KAAK,aAAa,EAAE,CAAC;YAEvC,OAAO,IAAI,CAAC,2BAA2B,CACrC,UAAU,EACV,SAAS,CACV,CAAA;QAEH,CAAC;QAED,OAAO,IAAI,CAAC,2BAA2B,CACrC,UAAU,EACV,SAAS,CACV,CAAA;IAEH,CAAC;IAED;;;;;;OAMG;IACI,2BAA2B,CAChC,UAAsB,EACtB,KAAa;QAGb,MAAM,aAAa,GACjB,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QAE5B,MAAM,KAAK,GAAG,KAAK,GAAG,CAAC,CAAA;QAEvB,MAAM,KAAK,GACT,CAAC,aAAa,GAAG,CAAC,CAAC,GAAG,CAAC,CAAA;QAEzB,OAAO;YACL,CAAC,EAAE,UAAU,CAAC,CAAC,GAAG,KAAK;YACvB,CAAC,EAAE,UAAU,CAAC,CAAC,GAAG,KAAK;SACxB,CAAA;IAEH,CAAC;IAED;;;;;;OAMG;IACI,2BAA2B,CAChC,UAAsB,EACtB,MAAc;QAGd,MAAM,YAAY,GAChB,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QAE7B,MAAM,KAAK,GACT,CAAC,YAAY,GAAG,CAAC,CAAC,GAAG,CAAC,CAAA;QAExB,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,CAAA;QAExB,OAAO;YACL,CAAC,EAAE,UAAU,CAAC,CAAC,GAAG,KAAK;YACvB,CAAC,EAAE,UAAU,CAAC,CAAC,GAAG,KAAK;SACxB,CAAA;IAEH,CAAC;CAEF"}