feat(hex): add center() function and method

When passed a hex (or used as a hex method) it returns the center point relative to the hex with
coordinates { q: 0, r: 0 }. When passed a hex prototype it returns the center relative to the
prototype's origin.

README.md

@@ -314,7 +314,7 @@ These methods exist in v3 and they need to be considered for v4.
   - [ ] ?   add
   - [x] ~~cartesian~~ replaced with `row` and `col` props
   - [x] ~~cartesianToCube (alias: toCube)~~ replaced with `offsetToAxial()`
-  - [ ] center
+  - [x] center
   - [x] ~~coordinates (returns cube by default?)~~ considered obsolete
   - [x] corners
   - [x] ~~cube~~ considered obsolete
@@ -430,7 +430,7 @@ These methods exist in v3 and they need to be considered for v4.
   - [x] ~~`grid.toMap()`~~ (just use `grid.store`)
   - [x] ~~`grid.toSet()`~~
 
-### ✅ Coordinates
+### Coordinates
 
 - [x] Store coordinates as ~~"tuples" (arrays)~~ simple 3D objects. ~~Investigate whether arrays or objects (without prototype?) (maybe even strings, ArrayBuffer?) are more performant.~~
 - [x] Take [Amit's advice](https://www.redblobgames.com/grids/hexagons/#coordinates-comparison) and use axial coordinates by default.

src/hex/functions/center.test.ts

@@ -0,0 +1,15 @@
+import { center } from './center'
+import { createHex } from './createHex'
+import { createHexPrototype } from './createHexPrototype'
+
+test('returns the center point relative to the hex with coordinates {q: 0, r: 0}, when a hex is passed', () => {
+  const hexPrototype = createHexPrototype({ dimensions: 10, origin: 'topLeft' })
+  const hex = createHex(hexPrototype, { q: 1, r: 2 })
+
+  expect(center(hex)).toEqual({ x: -34.64101615137754, y: -30 })
+})
+
+test(`returns the center point relative to any hex's origin, when a hex prototype is passed`, () => {
+  const hexPrototype = createHexPrototype({ dimensions: 10, origin: { x: 1, y: 2 } })
+  expect(center(hexPrototype)).toEqual({ x: 7.6602540378443855, y: 8 })
+})

src/hex/functions/center.ts

@@ -0,0 +1,10 @@
+import { Hex, HexPrototype, Point } from '../types'
+import { isHex } from './isHex'
+
+// todo: add to docs that when passed a hex, its center relative to the "origin hex" are returned (different per hex coordinates)
+// and when passed hex prototype, its center relative to any hex's origin are returned (always the same)
+export function center(hexOrPrototype: Hex | Pick<HexPrototype, 'width' | 'height' | 'origin'>): Point {
+  const { width, height } = hexOrPrototype
+  const { x, y } = isHex(hexOrPrototype) ? hexOrPrototype : hexOrPrototype.origin
+  return { x: width / 2 - x, y: height / 2 - y }
+}

src/hex/functions/createHexPrototype.test.ts

@@ -38,6 +38,12 @@ test('returns the default hex prototype when no options are passed', () => {
       enumerable: true,
       configurable: true,
     },
+    center: {
+      get: expect.any(Function),
+      set: undefined,
+      enumerable: false,
+      configurable: false,
+    },
     clone: {
       value: expect.any(Function),
       writable: true,

src/hex/functions/createHexPrototype.ts

@@ -1,5 +1,6 @@
 import { isFunction, isObject, isPoint } from '../../utils'
 import { BoundingBox, Ellipse, Hex, HexPrototype, HexSettings, Orientation, Point } from '../types'
+import { center } from './center'
 import { cloneHex } from './cloneHex'
 import { corners } from './corners'
 import { equals } from './equals'
@@ -46,6 +47,11 @@ export const createHexPrototype = <T extends Hex>(
     __isHoneycombHex: { value: true, writable: false },
     // todo: all props set with `value` are writable (somehow the default `writable: false` doesn't apply). Not sure if this is a problem though
     // see: Object.getOwnPropertyDescriptors(hexPrototype)
+    center: {
+      get() {
+        return center(this)
+      },
+    },
     col: {
       get() {
         return hexToOffset(this).col

src/hex/functions/index.ts

@@ -1,3 +1,4 @@
+export * from './center'
 export * from './cloneHex'
 export * from './corners'
 export * from './createHex'

src/hex/types.ts

@@ -53,6 +53,7 @@ export interface HexSettings {
 export interface HexPrototype extends HexSettings {
   readonly __isHoneycombHex: true
   readonly [Symbol.toStringTag]: 'Hex'
+  readonly center: Point
   readonly col: number
   readonly corners: Point[]
   readonly height: number