midgard-hex-grid 1.0.0 → 1.0.1

package/README.md

@@ -205,4 +205,105 @@ import { MIDGARD_HEX_GRID_VERSION } from './dist/index.js'
 
 ## License
 
-ISC
+ISC
+
+## Visual Demonstrations
+
+Midgard Hex Grid includes two complementary demonstrations.
+
+The Minimal Demonstration shows how little TypeScript is needed to create a grid. The Theory Demonstration explains the coordinate system: parity, the skeleton, and the two orientations.
+
+### Minimal Demonstration
+
+A grid is created with `new HexGrid()` and `createGrid()`. Each example below sets `hexDiameter` to 120 and uses `skeletonWidth: 2` and `skeletonHeight: 2`. For an X-dominated grid, `hexDiameter` is the hexagon's width. For a Y-dominated grid, it is the hexagon's height.
+
+`createGrid()` builds the complete grid around the skeleton and fills in the surrounding hexagons. These examples produce 17 hexagons. The four light coastal-blue hexagons are the skeleton, at (2,2), (4,2), (2,4), and (4,4). The cream hexagons are the surrounding fill. Both orientations use the same logical coordinates. Only the geometry changes.
+
+**X-dominated Hex Grid**
+
+![X-dominated grid of 17 pointy-top hexagons. The skeleton hexagons (2,2), (4,2), (2,4), and (4,4) are light coastal blue and labeled. The createXDominatedGrid example is shown beside the grid.](docs/images/minimal-x.png)
+
+**Y-dominated Hex Grid**
+
+![Y-dominated grid of 17 flat-top hexagons. The same skeleton coordinates (2,2), (4,2), (2,4), and (4,4) are light coastal blue and labeled. The createYDominatedGrid example is shown beside the grid.](docs/images/minimal-y.png)
+
+The functions below are the examples used by the Minimal Demonstration. Import `HexGrid` as shown in [Basic usage](#basic-usage).
+
+```ts
+import { HexGrid } from './dist/index.js'
+
+function createXDominatedGrid() {
+  const hexDiameter = 120
+  const hexGrid = new HexGrid('x-dominated')
+
+  const hexagons = hexGrid.createGrid({
+    hexDiameter,
+    skeletonWidth: 2,
+    skeletonHeight: 2
+  })
+
+  return hexagons
+}
+```
+
+```ts
+import { HexGrid } from './dist/index.js'
+
+function createYDominatedGrid() {
+  const hexDiameter = 120
+  const hexGrid = new HexGrid('y-dominated')
+
+  const hexagons = hexGrid.createGrid({
+    hexDiameter,
+    skeletonWidth: 2,
+    skeletonHeight: 2
+  })
+
+  return hexagons
+}
+```
+
+### Theory Demonstration
+
+The diagrams below show how a rectangular coordinate field becomes a hexagonal grid, and which movements are valid.
+
+#### Coordinate parity
+
+A valid Midgard coordinate is two even numbers, such as (2,2) or (4,4), or two odd numbers, such as (3,3) or (1,5). A mixed coordinate, such as (3,4), is invalid because its numbers have different parity.
+
+#### The skeleton foundation
+
+(2,2) is always the top-left skeleton hexagon. Every skeleton begins there, whatever the grid's size or orientation. A 1 × 1 skeleton contains only (2,2) as its skeleton hexagon. Increasing `skeletonWidth` or `skeletonHeight` extends the skeleton from that origin through further even coordinates, such as (4,2), (2,4), and (4,4).
+
+#### Grid orientation
+
+An X-dominated grid uses hexagons with pointed tops and bottoms. A Y-dominated grid uses hexagons with flat tops and bottoms. Both orientations follow the same parity rules, so a coordinate such as (2,2) keeps its logical identity when the geometry changes.
+
+**X-dominated — Coordinate System and Neighbour Movement**
+
+![X-dominated theory diagram. A rectangular coordinate field stands beside a pointy-top hex grid, showing the six valid neighbours of the center and the forbidden vertical movements.](docs/images/theory-x.png)
+
+The left figure maps the rectangular coordinates onto the hexagons. The right figure shows the six valid neighbours of the center hexagon and marks movement in the Y direction as forbidden.
+
+**Y-dominated — Coordinate System and Neighbour Movement**
+
+![Y-dominated theory diagram. A rectangular coordinate field stands beside a flat-top hex grid, showing the six valid neighbours of the center and the forbidden horizontal movements.](docs/images/theory-y.png)
+
+The same relationship holds for the Y-dominated orientation. The forbidden movements are in the X direction.
+
+### Explore the Demonstrations
+
+The rendered pages are not published at a separate public address. The source of each page is in this repository:
+
+- [Minimal Demonstration](demo/minimal.html)
+- [Theory Demonstration](demo/index.html)
+
+To run them locally, install the demo dependencies and start Vite from the `demo` directory. The `dev` script in `demo/package.json` runs `vite`.
+
+```bash
+cd demo
+npm install
+npm run dev
+```
+
+Vite prints a local address. The Theory Demonstration is `demo/index.html`, served at `/`. The Minimal Demonstration is `demo/minimal.html`.

package/demo/demo-minimal.ts

@@ -0,0 +1,531 @@
+import { HexGrid, type LayeredHexagon } from '../src/index.ts'
+
+/**
+ * ⬡ X-dominated Hex-grid
+ *
+ * The following TypeScript code generates an X-dominated hexagonal
+ * grid using the Midgard Hex Grid library.
+ *
+ * An X-dominated hexagon has a pointed top and a pointed bottom,
+ * with flat sides on the left and right.
+ *
+ * The `HexGrid` constructor selects the orientation. Passing
+ * `'x-dominated'` creates this pointy-top grid. The same class
+ * creates a flat-top grid when given `'y-dominated'`.
+ *
+ * - `hexDiameter` is the horizontal width of each hexagon, from the
+ *   left flat side to the right flat side. This example uses 120.
+ * - `skeletonWidth` and `skeletonHeight` are the skeleton dimensions,
+ *   counted in skeleton coordinates. This example uses 2 and 2.
+ *
+ * The skeleton is the rectangular core. It starts at coordinate
+ * (2, 2) and steps by two, so these dimensions are the four
+ * coordinates (2, 2), (4, 2), (2, 4), and (4, 4). `createGrid()`
+ * fills the surrounding hexagons automatically. A 2 × 2 skeleton
+ * generates 17 hexagons.
+ *
+ * Each hexagon in the returned array has its Midgard `coordinate`,
+ * its `center`, its six corner `points`, and a `zIndex`. The library
+ * does not generate SVG or HTML. Draw `points` with the graphics
+ * system the application already uses.
+ *
+ * Change `hexDiameter` to resize the hexagons. Change
+ * `skeletonWidth`, `skeletonHeight`, or both to create another grid
+ * size. The library recalculates the geometry.
+ *
+ * @returns The 17 hexagons of the complete grid, including the
+ * surrounding fill, with coordinates and geometry ready to render.
+ */
+function createXDominatedGrid() {
+  const hexDiameter = 120
+  const hexGrid = new HexGrid('x-dominated')
+
+  const hexagons = hexGrid.createGrid({
+    hexDiameter,
+    skeletonWidth: 2,
+    skeletonHeight: 2
+  })
+
+  return hexagons
+}
+
+/**
+ * ⬡ Y-dominated Hex-grid
+ *
+ * The following TypeScript code generates a Y-dominated hexagonal
+ * grid using the Midgard Hex Grid library.
+ *
+ * A Y-dominated hexagon has a flat top and a flat bottom, with
+ * points on the left and right.
+ *
+ * Both orientations use the same `HexGrid` class. The constructor
+ * argument selects the orientation: `'y-dominated'` here, and
+ * `'x-dominated'` in `createXDominatedGrid`.
+ *
+ * - For a Y-dominated grid, `hexDiameter` is the vertical hexagon
+ *   height, from the flat top to the flat bottom. The library
+ *   derives the horizontal width. This example uses 120.
+ * - `skeletonWidth` and `skeletonHeight` again describe a 2 × 2
+ *   skeleton.
+ *
+ * `createGrid()` fills the surrounding hexagons automatically and
+ * calculates their geometry. The returned array contains 17 hexagons.
+ *
+ * Each hexagon carries its `coordinate`, `center`, `points`, and
+ * `zIndex`. The application decides how to render that geometry.
+ * The library does not generate SVG or HTML.
+ *
+ * Change `hexDiameter` to change the hexagon height, or change the
+ * skeleton dimensions to change the grid. Keep the constructor
+ * argument `'y-dominated'` to keep the flat-top orientation.
+ *
+ * @returns The 17 hexagons of the complete grid, including the
+ * surrounding fill, with coordinates and geometry ready to render.
+ */
+function createYDominatedGrid() {
+  const hexDiameter = 120
+  const hexGrid = new HexGrid('y-dominated')
+
+  const hexagons = hexGrid.createGrid({
+    hexDiameter,
+    skeletonWidth: 2,
+    skeletonHeight: 2
+  })
+
+  return hexagons
+}
+
+/* =====================================================================
+ * PRESENTATION — SVG, HTML AND CSS
+ *
+ * The functions above generate the hexagons. Everything below only
+ * displays those results.
+ * ===================================================================== */
+
+const xDominatedHexagons = createXDominatedGrid()
+const yDominatedHexagons = createYDominatedGrid()
+
+const xDominatedSource = `function createXDominatedGrid() {
+  const hexDiameter = 120
+  const hexGrid = new HexGrid('x-dominated')
+
+  const hexagons = hexGrid.createGrid({
+    hexDiameter,
+    skeletonWidth: 2,
+    skeletonHeight: 2
+  })
+
+  return hexagons
+}`
+
+const yDominatedSource = `function createYDominatedGrid() {
+  const hexDiameter = 120
+  const hexGrid = new HexGrid('y-dominated')
+
+  const hexagons = hexGrid.createGrid({
+    hexDiameter,
+    skeletonWidth: 2,
+    skeletonHeight: 2
+  })
+
+  return hexagons
+}`
+
+const styles = `
+:root {
+  --page-navy: #0e1c2e;
+  --panel-parchment: #c7a47f;
+  --panel-shadow: 0 16px 36px rgba(0, 0, 0, 0.28);
+  --ink-strong: #2a1a0e;
+  --ink-body: #3d2918;
+  --ink-soft: #4a3120;
+  --rule-brown: #7a4e2d;
+}
+
+html {
+  font-size: 17px;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  background: var(--page-navy);
+  color: var(--ink-body);
+  font-family: Palatino, 'Palatino Linotype', 'Iowan Old Style', Georgia, serif;
+  line-height: 1.45;
+}
+
+.page {
+  padding: 32px 20px 48px;
+}
+
+.sheet {
+  width: 100%;
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 48px 40px 56px;
+  background: var(--panel-parchment);
+  box-shadow: var(--panel-shadow);
+}
+
+h1 {
+  margin: 0;
+  color: var(--ink-strong);
+  font-size: 40px;
+  font-weight: 600;
+  line-height: 1.15;
+  text-align: center;
+}
+
+.sheet__minimal {
+  display: block;
+  margin: 8px 0 0;
+  color: var(--ink-soft);
+  font-size: 18px;
+  font-weight: 600;
+  line-height: 1.25;
+  text-align: center;
+  text-decoration-line: underline;
+  text-decoration-thickness: 1px;
+  text-underline-offset: 0.2em;
+}
+
+.principle {
+  max-width: 820px;
+  margin: 36px auto;
+}
+
+.principle h2 {
+  margin: 0 0 16px;
+  color: var(--ink-strong);
+  font-size: 26px;
+  font-weight: 600;
+  line-height: 1.25;
+  text-align: center;
+}
+
+.principle p {
+  margin: 0 0 16px;
+  color: var(--ink-body);
+  line-height: 1.6;
+  text-align: left;
+}
+
+.principle p:last-child {
+  margin-bottom: 0;
+}
+
+.principle strong {
+  color: var(--ink-strong);
+  font-weight: 700;
+}
+
+.grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  align-items: center;
+  gap: 40px;
+  margin-top: 36px;
+}
+
+.grid__hex {
+  display: flex;
+  justify-content: center;
+}
+
+.grid polygon {
+  fill: #f4ead8;
+  stroke: #2a1a0e;
+  stroke-width: 2;
+  stroke-linejoin: round;
+}
+
+.grid polygon.skeleton {
+  fill: #d6f0f5;
+}
+
+.skeleton-label {
+  fill: #10283f;
+  font-family: Palatino, 'Palatino Linotype', 'Iowan Old Style', Georgia, serif;
+  text-anchor: middle;
+  dominant-baseline: central;
+}
+
+.skeleton-label__name {
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.skeleton-label__coordinate {
+  font-size: 23px;
+  font-weight: 700;
+}
+
+.grid__doc h2 {
+  margin: 0 0 12px;
+  padding-bottom: 8px;
+  border-bottom: 1px solid var(--rule-brown);
+  color: var(--ink-strong);
+  font-size: 26px;
+  font-weight: 600;
+  line-height: 1.25;
+}
+
+.grid__doc p {
+  margin: 0;
+}
+
+.grid pre {
+  margin: 18px 0 0;
+  padding: 22px 24px;
+  overflow-x: auto;
+  border-radius: 10px;
+  background: var(--page-navy);
+  box-shadow: 0 10px 24px rgba(14, 28, 46, 0.18);
+  color: #f4ead8;
+  font-family: ui-monospace, 'SF Mono', Menlo, Consolas, monospace;
+  font-size: 15px;
+  line-height: 1.6;
+}
+
+.grid code {
+  font-family: inherit;
+}
+
+.tok-keyword {
+  color: #e7c98a;
+}
+
+.tok-string {
+  color: #c9e2a6;
+}
+
+.tok-number {
+  color: #9fd4f0;
+}
+
+@media (max-width: 1100px) {
+  .grid {
+    grid-template-columns: 1fr;
+  }
+}
+
+@media (max-width: 980px) {
+  .sheet {
+    padding: 36px 22px 40px;
+  }
+
+  h1 {
+    font-size: 32px;
+  }
+}
+`
+
+const style = document.createElement('style')
+style.textContent = styles
+document.head.append(style)
+
+const page = document.createElement('main')
+page.className = 'page'
+
+const sheet = document.createElement('article')
+sheet.className = 'sheet'
+
+const heading = document.createElement('h1')
+heading.textContent = 'Midgard Hex Grid Minimal Demonstration'
+
+const theory = document.createElement('a')
+theory.className = 'sheet__minimal'
+theory.href = '/index.html'
+theory.textContent = 'Theory Demonstration'
+
+const headingSection = document.createElement('div')
+headingSection.append(heading, theory)
+
+sheet.append(
+  headingSection,
+  createPrincipleSection(),
+  createDemonstration(
+    xDominatedHexagons,
+    'X-dominated Hex-grid',
+    'The following TypeScript code generates an X-dominated hexagonal grid using the Midgard Hex Grid library.',
+    xDominatedSource
+  ),
+  createDemonstration(
+    yDominatedHexagons,
+    'Y-dominated Hex-grid',
+    'The following TypeScript code generates a Y-dominated hexagonal grid using the Midgard Hex Grid library.',
+    yDominatedSource
+  )
+)
+page.append(sheet)
+document.body.prepend(page)
+
+function createPrincipleSection() {
+  const section = document.createElement('section')
+  section.className = 'principle'
+
+  const heading = document.createElement('h2')
+  heading.textContent = '⬡ The Parity Principle & Grid Orientation'
+
+  const parity = document.createElement('p')
+  parity.append(
+    'Midgard Hex Grid is built on a simple mathematical principle called ',
+    strong('coordinate parity'),
+    '. Every valid hexagon coordinate consists of two numbers that are either both even or both odd. The even coordinates, such as (2,2), (4,2), (2,4), and (4,4), form the underlying ',
+    strong('skeleton grid'),
+    ', while the odd coordinates, such as (3,3), (1,3), and (3,5), identify the surrounding hexagons that complete the grid. Mixed coordinates, such as (3,4) or (2,5), are never valid because their numbers have different parity.'
+  )
+
+  const foundation = document.createElement('p')
+  foundation.append(
+    strong('The foundation of every grid is the skeleton hexagon at coordinate (2,2).'),
+    ' This is always the top-left skeleton hexagon and the fixed starting point from which the skeleton grid is constructed. Regardless of the grid\'s dimensions or orientation, the skeleton begins at (2,2). For example, when skeletonWidth: 1 and skeletonHeight: 1, the skeleton consists of exactly one hexagon: (2,2). Increasing the skeleton width or height extends the skeleton from this fixed origin, using even coordinates such as (4,2), (2,4), and (4,4). This makes (2,2) the permanent anchor of the Midgard coordinate system.'
+  )
+
+  const orientation = document.createElement('p')
+  orientation.append(
+    'The library supports two orientations: ',
+    strong('X-dominated'),
+    ' and ',
+    strong('Y-dominated'),
+    '. X-dominated grids use hexagons with pointed tops and bottoms, while Y-dominated grids use hexagons with flat tops and bottoms. Both orientations follow exactly the same parity rules and coordinate system; only the geometric arrangement changes. This means that a hexagon at coordinate (2,2) retains its logical identity regardless of orientation.'
+  )
+
+  const separation = document.createElement('p')
+  separation.append(
+    'By separating ',
+    strong('logical coordinates from visual geometry'),
+    ', Midgard Hex Grid provides a consistent foundation for creating, positioning, and navigating hexagonal grids in either orientation.'
+  )
+
+  section.append(heading, parity, foundation, orientation, separation)
+  return section
+}
+
+function strong(text: string) {
+  const element = document.createElement('strong')
+  element.textContent = text
+  return element
+}
+
+function createDemonstration(
+  hexagons: LayeredHexagon[],
+  title: string,
+  explanation: string,
+  source: string
+) {
+  const section = document.createElement('section')
+  section.className = 'grid'
+
+  const figure = document.createElement('div')
+  figure.className = 'grid__hex'
+  figure.append(renderHexagons(hexagons))
+
+  const heading = document.createElement('h2')
+  heading.textContent = title
+
+  const text = document.createElement('p')
+  text.textContent = explanation
+
+  const code = document.createElement('code')
+  fillCode(code, source)
+
+  const listing = document.createElement('pre')
+  listing.append(code)
+
+  const doc = document.createElement('div')
+  doc.className = 'grid__doc'
+  doc.append(heading, text, listing)
+
+  section.append(figure, doc)
+  return section
+}
+
+function fillCode(code: HTMLElement, source: string) {
+  const pattern = /'(?:\\.|[^'])*'|\b(?:const|function|new|return)\b|\b\d+\b/g
+  let cursor = 0
+
+  for (const match of source.matchAll(pattern)) {
+    const token = match[0]
+    const index = match.index
+    if (token === undefined || index === undefined) continue
+    if (index > cursor) code.append(source.slice(cursor, index))
+
+    const span = document.createElement('span')
+    span.className = token.startsWith("'")
+      ? 'tok-string'
+      : /^\d+$/.test(token)
+        ? 'tok-number'
+        : 'tok-keyword'
+    span.textContent = token
+    code.append(span)
+    cursor = index + token.length
+  }
+
+  if (cursor < source.length) code.append(source.slice(cursor))
+}
+
+function isSkeletonHexagon(hexagon: LayeredHexagon) {
+  const { x, y } = hexagon.coordinate
+  return (x === 2 && y === 2)
+    || (x === 4 && y === 2)
+    || (x === 2 && y === 4)
+    || (x === 4 && y === 4)
+}
+
+function renderHexagons(hexagons: LayeredHexagon[]) {
+  const firstPoint = hexagons[0]?.points[0]
+
+  if (firstPoint === undefined) {
+    throw new Error('The generated grid did not contain a hexagon.')
+  }
+
+  let minX = firstPoint.x
+  let minY = firstPoint.y
+  let maxX = firstPoint.x
+  let maxY = firstPoint.y
+
+  for (const hexagon of hexagons) {
+    for (const point of hexagon.points) {
+      if (point.x < minX) minX = point.x
+      if (point.y < minY) minY = point.y
+      if (point.x > maxX) maxX = point.x
+      if (point.y > maxY) maxY = point.y
+    }
+  }
+
+  const pad = 2
+  const width = maxX - minX + pad * 2
+  const height = maxY - minY + pad * 2
+  const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg')
+  svg.setAttribute('viewBox', `${minX - pad} ${minY - pad} ${width} ${height}`)
+  svg.setAttribute('width', String(width))
+  svg.setAttribute('height', String(height))
+
+  for (const hexagon of hexagons) {
+    const polygon = document.createElementNS('http://www.w3.org/2000/svg', 'polygon')
+    polygon.setAttribute('points', hexagon.points.map((point) => `${point.x},${point.y}`).join(' '))
+    if (isSkeletonHexagon(hexagon)) polygon.classList.add('skeleton')
+    svg.append(polygon)
+  }
+
+  for (const hexagon of hexagons) {
+    if (!isSkeletonHexagon(hexagon)) continue
+    svg.append(
+      skeletonText(hexagon.center.x, hexagon.center.y - 12, 'skeleton-label skeleton-label__name', 'skeleton hex'),
+      skeletonText(hexagon.center.x, hexagon.center.y + 12, 'skeleton-label skeleton-label__coordinate', `${hexagon.coordinate.x},${hexagon.coordinate.y}`)
+    )
+  }
+
+  return svg
+}
+
+function skeletonText(x: number, y: number, className: string, value: string) {
+  const text = document.createElementNS('http://www.w3.org/2000/svg', 'text')
+  text.setAttribute('x', String(x))
+  text.setAttribute('y', String(y))
+  text.setAttribute('class', className)
+  text.textContent = value
+  return text
+}