@project-gridmap/library 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Project Gridmap contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# Project Gridmap
+
+Project Gridmap is a content-agnostic hierarchical grid map renderer. It knows
+about layers, groups, items, and cells. It does not know what those things mean.
+
+The current root `index.html` is still the standalone Bible demo for GitHub
+Pages. The importable package in `src/` is deliberately generic so it can power
+that demo, The Bible Game, and other ordered datasets.
+
+## Install
+
+```bash
+npm install @project-gridmap/core
+```
+
+## Usage
+
+```js
+import { createGridmap } from '@project-gridmap/core';
+
+const map = createGridmap({
+  container: document.getElementById('map'),
+  data: {
+    layers: [
+      {
+        id: 'course',
+        label: 'Course',
+        groups: [
+          {
+            id: 'module-a',
+            label: 'Module A',
+            items: [
+              {
+                id: 'lesson-1',
+                label: 'Lesson 1',
+                shortLabel: 'L1',
+                cells: [
+                  { id: 'lesson-1.1', label: '1', value: 12 },
+                  { id: 'lesson-1.2', label: '2', value: 8 },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+  colours: {
+    'lesson-1': '#c6feff',
+  },
+  onSelectCell(cell) {
+    console.log(cell.id);
+  },
+});
+```
+
+## Data Model
+
+Gridmap uses a fixed neutral hierarchy:
+
+```txt
+layer > group > item > cell
+```
+
+The order of the input data is preserved. Cell `value` is optional and is used
+for relative mark sizing when `relativeMarkSize` is enabled.
+
+## API
+
+```js
+map.focusMap();
+map.focusGroup('module-a');
+map.focusItem('lesson-1');
+map.focusCell('lesson-1.2');
+map.selectCell('lesson-1.2');
+map.addLayer((helpers) => {});
+map.setData(data);
+map.setColours(colours);
+map.destroy();
+```
+
+Custom layers let applications draw domain-specific overlays without adding
+domain language to the library.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@project-gridmap/library",
+  "version": "0.1.0",
+  "description": "A content-agnostic hierarchical grid map renderer.",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "test": "node --test",
+    "typecheck": "node --check src/index.js && node --check src/model.js && node --check src/gridmap.js"
+  },
+  "keywords": [
+    "gridmap",
+    "treemap",
+    "visualization",
+    "canvas"
+  ],
+  "license": "MIT"
+}

package/src/gridmap.js

@@ -0,0 +1,682 @@
+'use strict';
+
+import { DEFAULT_WORLDS, buildGridmapModel, cellAt, normaliseGridmapData } from './model.js';
+
+const DEFAULT_THEME = {
+  background: '#0a0b0c',
+  text: '#f2efe8',
+  mutedText: '#a19d94',
+  faintText: '#5c5954',
+  cellLine: '#2a2c2e',
+  itemLine: '#7d7a74',
+  groupLine: '#aeaaa2',
+  layerLine: '#d9d5cd',
+  font: 'ui-monospace, "SF Mono", Menlo, Consolas, monospace',
+};
+
+const DEFAULT_OPTIONS = {
+  worlds: DEFAULT_WORLDS,
+  layout: 'auto',
+  colours: {},
+  colourBy: 'item',
+  showMarks: true,
+  markType: 'number',
+  markOpacity: 0.5,
+  relativeMarkSize: true,
+  markMaxSize: 0.4,
+  numberMinPx: 8,
+  itemLabels: 'short',
+  history: false,
+  theme: DEFAULT_THEME,
+  labels: {},
+};
+
+function mergeOptions(options) {
+  return {
+    ...DEFAULT_OPTIONS,
+    ...options,
+    worlds: { ...DEFAULT_WORLDS, ...(options.worlds ?? {}) },
+    theme: { ...DEFAULT_THEME, ...(options.theme ?? {}) },
+    labels: { ...(options.labels ?? {}) },
+  };
+}
+
+function createElement(tag, attrs = {}, parent) {
+  const el = document.createElement(tag);
+  for (const [key, value] of Object.entries(attrs)) {
+    if (key === 'class') el.className = value;
+    else if (key === 'text') el.textContent = value;
+    else el.setAttribute(key, value);
+  }
+  if (parent) parent.appendChild(el);
+  return el;
+}
+
+const median = (values, fallback = 1) => {
+  const sorted = values.filter((value) => Number.isFinite(value)).sort((a, b) => a - b);
+  return sorted.length ? sorted[sorted.length >> 1] : fallback;
+};
+
+export class Gridmap {
+  constructor(options) {
+    if (!options?.container) throw new TypeError('createGridmap requires a container element');
+    if (!options?.data) throw new TypeError('createGridmap requires data');
+
+    this.options = mergeOptions(options);
+    this.data = normaliseGridmapData(options.data);
+    this.container = options.container;
+    this.models = {};
+    this.model = null;
+    this.camera = { cx: 0, cy: 0, k: 1, free: false };
+    this.state = { hover: null, selected: null, focus: { level: 'map' } };
+    this.layers = new Set();
+    this.listeners = new Map();
+    this.frameRequested = false;
+    this.destroyed = false;
+    this.pointer = { x: 0, y: 0, inside: false, down: false, moved: false };
+    this.resizeObserver = null;
+
+    this.mount();
+    this.rebuildModels();
+    this.useLayout(this.layoutName());
+    this.bind();
+    this.render();
+    this.emit('ready', this);
+  }
+
+  mount() {
+    const style = getComputedStyle(this.container);
+    if (style.position === 'static') this.container.style.position = 'relative';
+    this.container.style.overflow = 'hidden';
+    this.container.style.background = this.options.theme.background;
+
+    this.root = createElement('div', { class: 'gridmap-root' }, this.container);
+    Object.assign(this.root.style, {
+      position: 'absolute',
+      inset: '0',
+      overflow: 'hidden',
+      touchAction: 'none',
+      userSelect: 'none',
+      fontFamily: this.options.theme.font,
+      color: this.options.theme.text,
+    });
+
+    this.canvas = createElement('canvas', { class: 'gridmap-canvas' }, this.root);
+    Object.assign(this.canvas.style, { position: 'absolute', inset: '0', width: '100%', height: '100%' });
+    this.ctx = this.canvas.getContext('2d');
+
+    this.overlay = createElement('div', { class: 'gridmap-overlay' }, this.root);
+    Object.assign(this.overlay.style, {
+      position: 'absolute',
+      inset: '0',
+      pointerEvents: 'none',
+      fontFamily: this.options.theme.font,
+      fontSize: '10px',
+      letterSpacing: '0.14em',
+      textTransform: 'uppercase',
+    });
+
+    this.tooltip = createElement('div', { class: 'gridmap-tooltip' }, this.root);
+    Object.assign(this.tooltip.style, {
+      position: 'absolute',
+      pointerEvents: 'none',
+      opacity: '0',
+      padding: '5px 8px',
+      background: this.options.theme.background,
+      borderLeft: `1px solid ${this.options.theme.itemLine}`,
+      color: this.options.theme.mutedText,
+      fontSize: '10px',
+      letterSpacing: '0.14em',
+      textTransform: 'uppercase',
+      lineHeight: '1.6',
+      transition: 'opacity 120ms',
+    });
+  }
+
+  bind() {
+    this.bound = {
+      resize: () => this.resize(),
+      pointerdown: (event) => this.onPointerDown(event),
+      pointermove: (event) => this.onPointerMove(event),
+      pointerup: (event) => this.onPointerUp(event),
+      pointerleave: (event) => this.onPointerLeave(event),
+      wheel: (event) => this.onWheel(event),
+      keydown: (event) => {
+        if (event.key === 'Escape') this.focusMap();
+      },
+    };
+
+    this.root.addEventListener('pointerdown', this.bound.pointerdown);
+    this.root.addEventListener('pointermove', this.bound.pointermove);
+    this.root.addEventListener('pointerup', this.bound.pointerup);
+    this.root.addEventListener('pointercancel', this.bound.pointerup);
+    this.root.addEventListener('pointerleave', this.bound.pointerleave);
+    this.root.addEventListener('wheel', this.bound.wheel, { passive: false });
+    window.addEventListener('keydown', this.bound.keydown);
+
+    if ('ResizeObserver' in window) {
+      this.resizeObserver = new ResizeObserver(this.bound.resize);
+      this.resizeObserver.observe(this.container);
+    } else {
+      window.addEventListener('resize', this.bound.resize);
+    }
+  }
+
+  rebuildModels() {
+    this.models = {};
+    for (const [name, world] of Object.entries(this.options.worlds)) {
+      const model = buildGridmapModel(this.data, world);
+      model.layout = name;
+      this.models[name] = model;
+    }
+  }
+
+  layoutName() {
+    if (this.options.layout !== 'auto') return this.options.layout;
+    return this.container.clientHeight > this.container.clientWidth ? 'portrait' : 'landscape';
+  }
+
+  useLayout(name) {
+    const old = this.model;
+    this.model = this.models[name] ?? Object.values(this.models)[0];
+    if (old && old !== this.model) {
+      const same = (collection, entity) => (entity ? this.model[collection][entity.index] : null);
+      this.state.hover = null;
+      this.state.selected = same('cells', this.state.selected);
+      const focus = this.state.focus;
+      this.state.focus = {
+        level: focus.level,
+        group: same('groups', focus.group),
+        item: same('items', focus.item),
+        cell: same('cells', focus.cell),
+      };
+    }
+    this.prepareMarks();
+    Object.assign(this.camera, this.cameraForFocus(), { free: false });
+    this.resize();
+  }
+
+  prepareMarks() {
+    const values = this.model.cells.map((cell) => cell.value);
+    this.medianValue = median(values);
+    const sortedValues = values.filter((value) => Number.isFinite(value)).sort((a, b) => a - b);
+    this.referenceValue = sortedValues[Math.floor(Math.max(0, sortedValues.length - 1) * 0.99)] ?? this.medianValue;
+  }
+
+  viewport() {
+    return {
+      w: Math.max(1, this.container.clientWidth),
+      h: Math.max(1, this.container.clientHeight),
+    };
+  }
+
+  resize() {
+    if (this.destroyed || !this.model) return;
+    const nextLayout = this.layoutName();
+    if (nextLayout !== this.model.layout) {
+      this.useLayout(nextLayout);
+      return;
+    }
+
+    const { w, h } = this.viewport();
+    const dpr = Math.min(window.devicePixelRatio || 1, 3);
+    this.canvas.width = Math.round(w * dpr);
+    this.canvas.height = Math.round(h * dpr);
+    this.dpr = dpr;
+    if (!this.camera.free) Object.assign(this.camera, this.cameraForFocus());
+    this.render();
+  }
+
+  on(type, listener) {
+    if (!this.listeners.has(type)) this.listeners.set(type, new Set());
+    this.listeners.get(type).add(listener);
+    return () => this.off(type, listener);
+  }
+
+  off(type, listener) {
+    this.listeners.get(type)?.delete(listener);
+  }
+
+  emit(type, payload) {
+    this.listeners.get(type)?.forEach((listener) => listener(payload, this));
+    const callback = this.options[`on${type[0].toUpperCase()}${type.slice(1)}`];
+    if (typeof callback === 'function') callback(payload, this);
+  }
+
+  addLayer(layer) {
+    this.layers.add(layer);
+    this.render();
+    return () => {
+      this.layers.delete(layer);
+      this.render();
+    };
+  }
+
+  setData(data) {
+    this.data = normaliseGridmapData(data);
+    this.rebuildModels();
+    this.useLayout(this.layoutName());
+    this.emit('dataChange', this.data);
+  }
+
+  setColours(colours = {}) {
+    this.options.colours = colours;
+    this.render();
+  }
+
+  setConfig(config = {}) {
+    this.options = mergeOptions({ ...this.options, ...config });
+    this.prepareMarks();
+    this.render();
+  }
+
+  getModel() {
+    return this.model;
+  }
+
+  getSelectedCell() {
+    return this.state.selected;
+  }
+
+  colourOf(entity, fallback = this.options.theme.itemLine) {
+    const key = this.options.colourBy === 'group' ? entity.groupId
+      : this.options.colourBy === 'layer' ? entity.layerId
+      : this.options.colourBy === 'cell' ? entity.id
+      : entity.itemId ?? entity.id;
+    return this.options.colours?.[key] ?? fallback;
+  }
+
+  toScreenX(x) {
+    const { w } = this.viewport();
+    return (x - this.camera.cx) * this.camera.k + w / 2;
+  }
+
+  toScreenY(y) {
+    const { h } = this.viewport();
+    return (y - this.camera.cy) * this.camera.k + h / 2;
+  }
+
+  toWorldX(x) {
+    const { w } = this.viewport();
+    return (x - w / 2) / this.camera.k + this.camera.cx;
+  }
+
+  toWorldY(y) {
+    const { h } = this.viewport();
+    return (y - h / 2) / this.camera.k + this.camera.cy;
+  }
+
+  frame(rect, fill = 0.92) {
+    const { w, h } = this.viewport();
+    const margin = Math.min(w, h) < 700 ? 24 : 56;
+    const availableW = Math.max(1, w - margin * 2);
+    const availableH = Math.max(1, h - margin * 2);
+    const k = Math.min(availableW / rect.width, availableH / rect.height, (w * fill) / rect.width, (h * fill) / rect.height);
+    return { cx: rect.x + rect.width / 2, cy: rect.y + rect.height / 2, k };
+  }
+
+  clampK(k) {
+    const min = this.frame(this.model.world).k * 0.55;
+    const max = Math.min(this.viewport().w, this.viewport().h) * 0.9 / this.model.cellSide;
+    return Math.min(Math.max(k, min), max);
+  }
+
+  setCamera(cx, cy, k) {
+    const world = this.model.world;
+    this.camera.k = this.clampK(k);
+    this.camera.cx = Math.min(Math.max(cx, world.x), world.x + world.width);
+    this.camera.cy = Math.min(Math.max(cy, world.y), world.y + world.height);
+    this.camera.free = true;
+    this.render();
+  }
+
+  zoomAround(sx, sy, wx, wy, k) {
+    k = this.clampK(k);
+    this.setCamera(wx - (sx - this.viewport().w / 2) / k, wy - (sy - this.viewport().h / 2) / k, k);
+  }
+
+  focusRegion() {
+    const focus = this.state.focus;
+    if (focus.level === 'cell') return [focus.cell];
+    if (focus.level === 'item') return [focus.item];
+    if (focus.level === 'group') return focus.group.items;
+    return null;
+  }
+
+  cameraForFocus() {
+    const focus = this.state.focus;
+    if (focus.level === 'cell') return this.frame(focus.cell, 0.42);
+    if (focus.level === 'item') return this.frame(focus.item, 0.72);
+    if (focus.level === 'group') return this.frame(focus.group.bounds, 0.9);
+    return this.frame(this.model.world);
+  }
+
+  setFocus(level, value = null) {
+    const focus = { level };
+    if (level === 'group') focus.group = typeof value === 'string'
+      ? this.model.groups.find((group) => group.uid === value || group.id === value)
+      : value;
+    if (level === 'item') focus.item = typeof value === 'string'
+      ? this.model.items.find((item) => item.id === value)
+      : value;
+    if (level === 'cell') focus.cell = typeof value === 'string'
+      ? this.model.cells.find((cell) => cell.id === value)
+      : value;
+    if ((level !== 'map' && !focus[level])) return false;
+    if (focus.item) focus.group = this.model.groups[focus.item.groupIndex];
+    if (focus.cell) {
+      focus.item = this.model.items[focus.cell.itemIndex];
+      focus.group = this.model.groups[focus.cell.groupIndex];
+    }
+    this.state.focus = focus;
+    Object.assign(this.camera, this.cameraForFocus(), { free: false });
+    this.emit('focusChange', focus);
+    this.render();
+    return true;
+  }
+
+  focusMap() { return this.setFocus('map'); }
+  focusGroup(idOrGroup) { return this.setFocus('group', idOrGroup); }
+  focusItem(idOrItem) { return this.setFocus('item', idOrItem); }
+  focusCell(idOrCell) { return this.setFocus('cell', idOrCell); }
+
+  selectCell(idOrCell) {
+    const cell = typeof idOrCell === 'string'
+      ? this.model.cells.find((candidate) => candidate.id === idOrCell)
+      : idOrCell;
+    if (!cell) return false;
+    this.state.selected = cell;
+    this.emit('selectCell', cell);
+    this.render();
+    return true;
+  }
+
+  hitTest(sx, sy) {
+    const cell = cellAt(this.model, this.toWorldX(sx), this.toWorldY(sy));
+    const focus = this.state.focus;
+    if (focus.level === 'cell') return cell === focus.cell ? cell : null;
+    if (focus.level === 'item') return cell && cell.itemIndex === focus.item.index ? cell : null;
+    if (focus.level === 'group') return cell && cell.groupIndex === focus.group.index ? cell : null;
+    return cell;
+  }
+
+  onPointerDown(event) {
+    if (event.pointerType === 'mouse' && event.button !== 0) return;
+    this.pointer = {
+      x: event.clientX,
+      y: event.clientY,
+      startX: event.clientX,
+      startY: event.clientY,
+      cam: { ...this.camera },
+      inside: true,
+      down: true,
+      moved: false,
+    };
+    this.root.setPointerCapture?.(event.pointerId);
+  }
+
+  onPointerMove(event) {
+    const rect = this.root.getBoundingClientRect();
+    const x = event.clientX - rect.left;
+    const y = event.clientY - rect.top;
+
+    if (this.pointer.down) {
+      const dx = event.clientX - this.pointer.startX;
+      const dy = event.clientY - this.pointer.startY;
+      if (Math.hypot(dx, dy) > 4) this.pointer.moved = true;
+      if (this.pointer.moved) {
+        const cam = this.pointer.cam;
+        this.setCamera(cam.cx - dx / cam.k, cam.cy - dy / cam.k, cam.k);
+      }
+      return;
+    }
+
+    const hover = this.hitTest(x, y);
+    if (hover !== this.state.hover) {
+      this.state.hover = hover;
+      this.emit('hoverCell', hover);
+      this.render();
+    }
+    this.showTooltip(hover, x, y);
+  }
+
+  onPointerUp(event) {
+    if (!this.pointer.down) return;
+    const rect = this.root.getBoundingClientRect();
+    const x = event.clientX - rect.left;
+    const y = event.clientY - rect.top;
+    const wasTap = !this.pointer.moved;
+    this.pointer.down = false;
+    if (wasTap) {
+      const cell = this.hitTest(x, y);
+      if (cell) this.selectCell(cell);
+      else this.focusMap();
+    }
+  }
+
+  onPointerLeave() {
+    if (this.pointer.down) return;
+    this.state.hover = null;
+    this.showTooltip(null);
+    this.render();
+  }
+
+  onWheel(event) {
+    event.preventDefault();
+    const rect = this.root.getBoundingClientRect();
+    const x = event.clientX - rect.left;
+    const y = event.clientY - rect.top;
+    const dy = event.deltaY * (event.deltaMode === 1 ? 16 : 1);
+    this.zoomAround(x, y, this.toWorldX(x), this.toWorldY(y), this.camera.k * Math.exp(-dy * 0.0015));
+  }
+
+  showTooltip(cell, x, y) {
+    this.tooltip.style.opacity = cell ? '1' : '0';
+    if (!cell) return;
+    const format = this.options.labels.tooltip;
+    this.tooltip.textContent = typeof format === 'function'
+      ? format(cell, this)
+      : `${cell.groupLabel} / ${cell.itemLabel} / ${cell.label}`;
+    const width = this.tooltip.offsetWidth;
+    const height = this.tooltip.offsetHeight;
+    const { w, h } = this.viewport();
+    const left = x + 18 + width > w ? x - 18 - width : x + 18;
+    const top = y + 18 + height > h ? y - 18 - height : y + 18;
+    this.tooltip.style.transform = `translate(${Math.max(8, left)}px, ${Math.max(8, top)}px)`;
+  }
+
+  requestRender() {
+    if (this.frameRequested) return;
+    this.frameRequested = true;
+    requestAnimationFrame(() => {
+      this.frameRequested = false;
+      this.render();
+    });
+  }
+
+  render() {
+    if (!this.model || this.destroyed) return;
+    const { w, h } = this.viewport();
+    const ctx = this.ctx;
+    const theme = this.options.theme;
+    const k = this.camera.k;
+    const ox = w / 2 - this.camera.cx * k;
+    const oy = h / 2 - this.camera.cy * k;
+    const X = (x) => x * k + ox;
+    const Y = (y) => y * k + oy;
+    const rect = (r) => ctx.rect(X(r.x), Y(r.y), r.width * k, r.height * k);
+    const onScreen = (r) => X(r.x) < w && X(r.x + r.width) > 0 && Y(r.y) < h && Y(r.y + r.height) > 0;
+
+    ctx.setTransform(this.dpr || 1, 0, 0, this.dpr || 1, 0, 0);
+    ctx.clearRect(0, 0, w, h);
+    ctx.fillStyle = theme.background;
+    ctx.fillRect(0, 0, w, h);
+    ctx.lineWidth = 1;
+    ctx.setLineDash([]);
+
+    const visibleItems = this.model.items.filter(onScreen);
+
+    const hover = this.state.hover;
+    if (hover) {
+      ctx.fillStyle = theme.text;
+      ctx.globalAlpha = 0.07;
+      ctx.beginPath();
+      rect(hover);
+      ctx.fill();
+      ctx.globalAlpha = 1;
+    }
+
+    const lineAlpha = Math.min(1, Math.max(0, (this.model.cellSide * k - 6) / 6));
+    if (lineAlpha > 0) {
+      ctx.globalAlpha = lineAlpha;
+      ctx.strokeStyle = theme.cellLine;
+      ctx.beginPath();
+      for (const item of visibleItems) for (const cell of item.cells) if (onScreen(cell)) rect(cell);
+      ctx.stroke();
+      ctx.globalAlpha = 1;
+    }
+
+    for (const item of visibleItems) {
+      ctx.strokeStyle = this.colourOf(item, theme.itemLine);
+      ctx.globalAlpha = 0.9;
+      ctx.beginPath();
+      rect(item);
+      ctx.stroke();
+    }
+
+    ctx.globalAlpha = 1;
+    ctx.strokeStyle = theme.groupLine;
+    ctx.lineWidth = 1.25;
+    ctx.beginPath();
+    for (const group of this.model.groups) {
+      for (const segment of group.outline.filter((sg) => sg.betweenGroups)) {
+        ctx.moveTo(X(segment.x1), Y(segment.y1));
+        ctx.lineTo(X(segment.x2), Y(segment.y2));
+      }
+    }
+    ctx.stroke();
+
+    ctx.strokeStyle = theme.layerLine;
+    ctx.lineWidth = 1.5;
+    ctx.beginPath();
+    this.model.layers.forEach(rect);
+    ctx.stroke();
+
+    const selected = this.state.selected;
+    if (selected) {
+      const colour = this.colourOf(selected, theme.text);
+      ctx.strokeStyle = colour;
+      ctx.fillStyle = colour;
+      ctx.globalAlpha = 0.1;
+      ctx.beginPath();
+      rect(selected);
+      ctx.fill();
+      ctx.globalAlpha = 1;
+      ctx.lineWidth = 1.5;
+      ctx.beginPath();
+      rect(selected);
+      ctx.stroke();
+    }
+
+    if (this.options.showMarks) this.renderMarks(ctx, X, Y, onScreen);
+
+    for (const layer of this.layers) {
+      layer({
+        ctx,
+        model: this.model,
+        state: this.state,
+        camera: this.camera,
+        rect,
+        toScreenX: X,
+        toScreenY: Y,
+        colourOf: (entity, fallback) => this.colourOf(entity, fallback),
+        theme,
+      });
+    }
+
+    this.renderVeil(ctx, rect);
+    this.renderLabels(X, Y);
+  }
+
+  renderMarks(ctx, X, Y, onScreen) {
+    const theme = this.options.theme;
+    const useNumbers = this.options.markType === 'number' && this.model.cellSide * this.camera.k >= this.options.numberMinPx;
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+    for (const item of this.model.items) {
+      ctx.fillStyle = this.colourOf(item, theme.text);
+      for (const cell of item.cells) {
+        if (!onScreen(cell)) continue;
+        const scale = this.options.relativeMarkSize && cell.value
+          ? Math.max(0.35, Math.sqrt(cell.value / this.referenceValue))
+          : 0.7;
+        const size = Math.min(cell.width, cell.height) * this.options.markMaxSize * scale * this.camera.k;
+        ctx.globalAlpha = cell === this.state.hover || cell === this.state.selected ? 1 : this.options.markOpacity;
+        if (useNumbers) {
+          ctx.font = `${cell === this.state.hover || cell === this.state.selected ? 500 : 400} ${Math.max(2, Math.min(24, size))}px ${theme.font}`;
+          ctx.fillText(cell.label, X(cell.centerX), Y(cell.centerY));
+        } else {
+          const radius = Math.min(4, Math.max(1.2, size / 8));
+          ctx.beginPath();
+          ctx.arc(X(cell.centerX), Y(cell.centerY), radius, 0, Math.PI * 2);
+          ctx.fill();
+        }
+      }
+    }
+    ctx.globalAlpha = 1;
+  }
+
+  renderVeil(ctx, rect) {
+    const region = this.focusRegion();
+    if (!region) return;
+    const { w, h } = this.viewport();
+    ctx.fillStyle = this.options.theme.background;
+    ctx.globalAlpha = 0.66;
+    ctx.beginPath();
+    ctx.rect(0, 0, w, h);
+    region.forEach(rect);
+    ctx.fill('evenodd');
+    ctx.globalAlpha = 1;
+  }
+
+  renderLabels(X, Y) {
+    const labelItem = this.options.labels.item;
+    const selected = this.state.selected;
+    this.overlay.replaceChildren();
+    for (const item of this.model.items) {
+      const w = item.width * this.camera.k;
+      const h = item.height * this.camera.k;
+      if (w < 28 || h < 14) continue;
+      const text = typeof labelItem === 'function'
+        ? labelItem(item, this)
+        : this.options.itemLabels === 'full' ? item.label : item.shortLabel;
+      const el = createElement('div', { text }, this.overlay);
+      Object.assign(el.style, {
+        position: 'absolute',
+        left: `${X(item.x) + 5}px`,
+        top: `${Y(item.y) - 6}px`,
+        maxWidth: `${Math.max(20, w - 10)}px`,
+        overflow: 'hidden',
+        whiteSpace: 'nowrap',
+        textOverflow: 'clip',
+        color: this.colourOf(item, this.options.theme.mutedText),
+        background: this.options.theme.background,
+        padding: '0 4px',
+        opacity: selected?.itemIndex === item.index ? '1' : '0.78',
+      });
+    }
+  }
+
+  destroy() {
+    this.destroyed = true;
+    this.resizeObserver?.disconnect();
+    window.removeEventListener('resize', this.bound?.resize);
+    window.removeEventListener('keydown', this.bound?.keydown);
+    this.root.remove();
+    this.listeners.clear();
+  }
+}
+
+export function createGridmap(options) {
+  return new Gridmap(options);
+}

package/src/index.d.ts

@@ -0,0 +1,200 @@
+export type GridmapCellInput = {
+  id?: string | number;
+  label?: string;
+  value?: number | null;
+  meta?: Record<string, unknown>;
+};
+
+export type GridmapItemInput = {
+  id?: string;
+  key?: string;
+  label?: string;
+  name?: string;
+  shortLabel?: string;
+  cells?: Array<GridmapCellInput | string | number>;
+  cellCount?: number;
+  cellsCount?: number;
+  meta?: Record<string, unknown>;
+};
+
+export type GridmapGroupInput = {
+  id?: string;
+  label?: string;
+  name?: string;
+  items: GridmapItemInput[];
+  meta?: Record<string, unknown>;
+};
+
+export type GridmapLayerInput = {
+  id?: string;
+  label?: string;
+  name?: string;
+  groups?: GridmapGroupInput[];
+  items?: GridmapItemInput[];
+  meta?: Record<string, unknown>;
+};
+
+export type GridmapData = {
+  layers: GridmapLayerInput[];
+  meta?: Record<string, unknown>;
+};
+
+export type GridmapRect = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+
+export type GridmapCell = GridmapRect & {
+  index: number;
+  id: string;
+  label: string;
+  value: number | null;
+  meta: Record<string, unknown>;
+  layerId: string;
+  layerLabel: string;
+  layerIndex: number;
+  groupId: string;
+  groupLabel: string;
+  groupIndex: number;
+  itemId: string;
+  itemLabel: string;
+  itemShortLabel: string;
+  itemIndex: number;
+  ordinal: number;
+  centerX: number;
+  centerY: number;
+};
+
+export type GridmapItem = GridmapRect & {
+  index: number;
+  id: string;
+  label: string;
+  shortLabel: string;
+  meta: Record<string, unknown>;
+  layerId: string;
+  layerLabel: string;
+  layerIndex: number;
+  groupId: string;
+  groupLabel: string;
+  groupIndex: number;
+  cellCount: number;
+  cells: GridmapCell[];
+};
+
+export type GridmapGroup = {
+  index: number;
+  uid: string;
+  id: string;
+  label: string;
+  meta: Record<string, unknown>;
+  layerId: string;
+  layerLabel: string;
+  layerIndex: number;
+  items: GridmapItem[];
+  bounds: GridmapRect;
+  outline: Array<{ x1: number; y1: number; x2: number; y2: number; betweenGroups: boolean }>;
+};
+
+export type GridmapLayer = GridmapRect & {
+  index: number;
+  id: string;
+  label: string;
+  meta: Record<string, unknown>;
+  groups: GridmapGroup[];
+  items: GridmapItem[];
+};
+
+export type GridmapModel = {
+  data: GridmapData;
+  world: GridmapRect & { gutter?: number };
+  layout?: string;
+  cellSide: number;
+  layers: GridmapLayer[];
+  groups: GridmapGroup[];
+  items: GridmapItem[];
+  cells: GridmapCell[];
+};
+
+export type GridmapTheme = {
+  background: string;
+  text: string;
+  mutedText: string;
+  faintText: string;
+  cellLine: string;
+  itemLine: string;
+  groupLine: string;
+  layerLine: string;
+  font: string;
+};
+
+export type GridmapLayerPainter = (args: {
+  ctx: CanvasRenderingContext2D;
+  model: GridmapModel;
+  state: {
+    hover: GridmapCell | null;
+    selected: GridmapCell | null;
+    focus: Record<string, unknown>;
+  };
+  camera: { cx: number; cy: number; k: number; free: boolean };
+  rect: (rect: GridmapRect) => void;
+  toScreenX: (x: number) => number;
+  toScreenY: (y: number) => number;
+  colourOf: (entity: GridmapCell | GridmapItem, fallback?: string) => string;
+  theme: GridmapTheme;
+}) => void;
+
+export type GridmapOptions = {
+  container: HTMLElement;
+  data: GridmapData;
+  worlds?: Record<string, GridmapRect & { gutter?: number }>;
+  layout?: 'auto' | string;
+  colours?: Record<string, string>;
+  colourBy?: 'item' | 'group' | 'layer' | 'cell';
+  showMarks?: boolean;
+  markType?: 'number' | 'dot';
+  markOpacity?: number;
+  relativeMarkSize?: boolean;
+  markMaxSize?: number;
+  numberMinPx?: number;
+  itemLabels?: 'short' | 'full';
+  history?: boolean;
+  theme?: Partial<GridmapTheme>;
+  labels?: {
+    item?: (item: GridmapItem, map: Gridmap) => string;
+    tooltip?: (cell: GridmapCell, map: Gridmap) => string;
+  };
+  onReady?: (map: Gridmap) => void;
+  onHoverCell?: (cell: GridmapCell | null, map: Gridmap) => void;
+  onSelectCell?: (cell: GridmapCell, map: Gridmap) => void;
+  onFocusChange?: (focus: Record<string, unknown>, map: Gridmap) => void;
+  onDataChange?: (data: GridmapData, map: Gridmap) => void;
+};
+
+export const DEFAULT_WORLDS: Record<string, GridmapRect & { gutter: number }>;
+
+export function normaliseGridmapData(data: GridmapData): GridmapData;
+export function buildGridmapModel(data: GridmapData, world?: GridmapRect & { gutter?: number }): GridmapModel;
+export function validateGridmapModel(model: GridmapModel): true;
+export function cellAt(model: GridmapModel, x: number, y: number): GridmapCell | null;
+export function itemsOf(layer: GridmapLayerInput): GridmapItemInput[];
+export function createGridmap(options: GridmapOptions): Gridmap;
+
+export class Gridmap {
+  constructor(options: GridmapOptions);
+  on(type: string, listener: (payload: unknown, map: Gridmap) => void): () => void;
+  off(type: string, listener: (payload: unknown, map: Gridmap) => void): void;
+  addLayer(layer: GridmapLayerPainter): () => void;
+  setData(data: GridmapData): void;
+  setColours(colours?: Record<string, string>): void;
+  setConfig(config?: Partial<GridmapOptions>): void;
+  getModel(): GridmapModel;
+  getSelectedCell(): GridmapCell | null;
+  focusMap(): boolean;
+  focusGroup(idOrGroup: string | GridmapGroup): boolean;
+  focusItem(idOrItem: string | GridmapItem): boolean;
+  focusCell(idOrCell: string | GridmapCell): boolean;
+  selectCell(idOrCell: string | GridmapCell): boolean;
+  destroy(): void;
+}

package/src/index.js

@@ -0,0 +1,12 @@
+'use strict';
+
+export {
+  DEFAULT_WORLDS,
+  buildGridmapModel,
+  cellAt,
+  itemsOf,
+  normaliseGridmapData,
+  validateGridmapModel,
+} from './model.js';
+
+export { Gridmap, createGridmap } from './gridmap.js';

package/src/model.js

@@ -0,0 +1,375 @@
+'use strict';
+
+export const DEFAULT_WORLDS = {
+  portrait: { x: 0, y: 0, width: 1000, height: 1900, gutter: 30 },
+  landscape: { x: 0, y: 0, width: 1600, height: 1000, gutter: 30 },
+};
+
+const EPS = 1e-6;
+const near = (a, b) => Math.abs(a - b) < EPS;
+const slug = (s) => String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+const cellCount = (item) => item.cells.length;
+const weightSum = (items) => items.reduce((sum, item) => sum + item.n, 0);
+
+function assertObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object`);
+  }
+}
+
+function normaliseCell(cell, index) {
+  if (typeof cell === 'string' || typeof cell === 'number') {
+    return { id: String(cell), label: String(cell), value: null, meta: {} };
+  }
+  assertObject(cell, `cell ${index + 1}`);
+  const id = cell.id ?? String(index + 1);
+  return {
+    ...cell,
+    id: String(id),
+    label: String(cell.label ?? id),
+    value: Number.isFinite(cell.value) ? cell.value : null,
+    meta: cell.meta ?? {},
+  };
+}
+
+function normaliseItem(item, index) {
+  assertObject(item, `item ${index + 1}`);
+  const id = item.id ?? item.key ?? slug(item.label ?? item.name ?? `item-${index + 1}`);
+  const cells = item.cells ?? Array.from({ length: item.cellCount ?? item.cellsCount ?? 0 }, (_, i) => i + 1);
+  if (!Array.isArray(cells) || cells.length === 0) {
+    throw new TypeError(`item ${id} must include at least one cell`);
+  }
+  return {
+    ...item,
+    id: String(id),
+    label: String(item.label ?? item.name ?? id),
+    shortLabel: item.shortLabel ? String(item.shortLabel) : String(item.key ?? id),
+    cells: cells.map(normaliseCell),
+    meta: item.meta ?? {},
+  };
+}
+
+function normaliseGroup(group, index) {
+  assertObject(group, `group ${index + 1}`);
+  const id = group.id ?? slug(group.label ?? group.name ?? `group-${index + 1}`);
+  const items = group.items ?? [];
+  if (!Array.isArray(items) || items.length === 0) {
+    throw new TypeError(`group ${id} must include at least one item`);
+  }
+  return {
+    ...group,
+    id: String(id),
+    label: String(group.label ?? group.name ?? id),
+    items: items.map(normaliseItem),
+    meta: group.meta ?? {},
+  };
+}
+
+function normaliseLayer(layer, index) {
+  assertObject(layer, `layer ${index + 1}`);
+  const id = layer.id ?? slug(layer.label ?? layer.name ?? `layer-${index + 1}`);
+  const groups = layer.groups ?? (Array.isArray(layer.items)
+    ? [{ id: 'default', label: String(layer.label ?? layer.name ?? id), items: layer.items }]
+    : []);
+  if (!Array.isArray(groups) || groups.length === 0) {
+    throw new TypeError(`layer ${id} must include at least one group`);
+  }
+  return {
+    ...layer,
+    id: String(id),
+    label: String(layer.label ?? layer.name ?? id),
+    groups: groups.map(normaliseGroup),
+    meta: layer.meta ?? {},
+  };
+}
+
+export function normaliseGridmapData(data) {
+  assertObject(data, 'gridmap data');
+  if (!Array.isArray(data.layers) || data.layers.length === 0) {
+    throw new TypeError('gridmap data must include at least one layer');
+  }
+  return {
+    ...data,
+    layers: data.layers.map(normaliseLayer),
+    meta: data.meta ?? {},
+  };
+}
+
+export const itemsOf = (layer) => layer.groups.flatMap((group) =>
+  group.items.map((item) => ({ ...item, groupId: group.id, groupLabel: group.label, groupMeta: group.meta })));
+
+function rowCounts(n, rows) {
+  const base = Math.floor(n / rows);
+  const extra = n % rows;
+  return Array.from({ length: rows }, (_, i) => base + (i >= rows - extra ? 1 : 0));
+}
+
+function gridCost(n, width, height, rows) {
+  let sum = 0;
+  let worst = 0;
+  for (const count of rowCounts(n, rows)) {
+    const error = Math.log((width / count) / (height * count / n)) ** 2;
+    sum += count * error;
+    worst = Math.max(worst, error);
+  }
+  return sum + 2 * worst;
+}
+
+function bestGrid(n, width, height) {
+  let best = { rows: 1, cost: Infinity };
+  for (let rows = 1; rows <= n; rows += 1) {
+    const cost = gridCost(n, width, height, rows);
+    if (cost < best.cost) best = { rows, cost };
+  }
+  return best;
+}
+
+function cut(rect, fraction) {
+  return rect.width >= rect.height
+    ? [
+      { x: rect.x, y: rect.y, width: rect.width * fraction, height: rect.height },
+      { x: rect.x + rect.width * fraction, y: rect.y, width: rect.width * (1 - fraction), height: rect.height },
+    ]
+    : [
+      { x: rect.x, y: rect.y, width: rect.width, height: rect.height * fraction },
+      { x: rect.x, y: rect.y + rect.height * fraction, width: rect.width, height: rect.height * (1 - fraction) },
+    ];
+}
+
+const SPLIT_CANDIDATES = 3;
+
+function partitionItems(items, rect) {
+  if (items.length === 1) {
+    return { cost: bestGrid(items[0].n, rect.width, rect.height).cost, regions: [{ ...items[0], rect }] };
+  }
+
+  const total = weightSum(items);
+  const splits = [];
+  for (let k = 1, acc = 0; k < items.length; k += 1) {
+    acc += items[k - 1].n;
+    splits.push({ k, imbalance: Math.abs(acc - total / 2) });
+  }
+  splits.sort((a, b) => a.imbalance - b.imbalance || a.k - b.k);
+
+  let best = null;
+  for (const { k } of splits.slice(0, SPLIT_CANDIDATES)) {
+    const first = items.slice(0, k);
+    const rest = items.slice(k);
+    const [aRect, bRect] = cut(rect, weightSum(first) / total);
+    const a = partitionItems(first, aRect);
+    const b = partitionItems(rest, bRect);
+    if (!best || a.cost + b.cost < best.cost) {
+      best = { cost: a.cost + b.cost, regions: [...a.regions, ...b.regions] };
+    }
+  }
+  return best;
+}
+
+function layoutCells(cells, x, y, width, height) {
+  const regions = [];
+  let cy = y;
+  for (const count of rowCounts(cells.length, bestGrid(cells.length, width, height).rows)) {
+    const rowHeight = height * count / cells.length;
+    for (let i = 0; i < count; i += 1) {
+      regions.push({
+        x: x + width * i / count,
+        y: cy,
+        width: width / count,
+        height: rowHeight,
+      });
+    }
+    cy += rowHeight;
+  }
+  return regions;
+}
+
+function boundsOf(rects) {
+  const x = Math.min(...rects.map((r) => r.x));
+  const y = Math.min(...rects.map((r) => r.y));
+  const x2 = Math.max(...rects.map((r) => r.x + r.width));
+  const y2 = Math.max(...rects.map((r) => r.y + r.height));
+  return { x, y, width: x2 - x, height: y2 - y };
+}
+
+function subtractIntervals(lo, hi, cuts) {
+  const pieces = [];
+  let cur = lo;
+  for (const [a, b] of [...cuts].sort((p, q) => p[0] - q[0])) {
+    if (b <= cur + EPS) continue;
+    if (a > cur + EPS) pieces.push([cur, Math.min(a, hi)]);
+    cur = Math.max(cur, b);
+    if (cur >= hi - EPS) break;
+  }
+  if (cur < hi - EPS) pieces.push([cur, hi]);
+  return pieces.filter(([a, b]) => b - a > EPS);
+}
+
+function regionOutline(rects) {
+  const segments = [];
+  for (const rect of rects) {
+    const left = rect.x;
+    const right = rect.x + rect.width;
+    const top = rect.y;
+    const bottom = rect.y + rect.height;
+    const sides = [
+      { at: top, lo: left, hi: right, horizontal: true, meets: (other) => other.y + other.height },
+      { at: bottom, lo: left, hi: right, horizontal: true, meets: (other) => other.y },
+      { at: left, lo: top, hi: bottom, horizontal: false, meets: (other) => other.x + other.width },
+      { at: right, lo: top, hi: bottom, horizontal: false, meets: (other) => other.x },
+    ];
+
+    for (const side of sides) {
+      const covered = rects
+        .filter((other) => other !== rect && near(side.meets(other), side.at))
+        .map((other) => (side.horizontal ? [other.x, other.x + other.width] : [other.y, other.y + other.height]));
+
+      for (const [a, b] of subtractIntervals(side.lo, side.hi, covered)) {
+        segments.push(side.horizontal
+          ? { x1: a, y1: side.at, x2: b, y2: side.at }
+          : { x1: side.at, y1: a, x2: side.at, y2: b });
+      }
+    }
+  }
+  return segments;
+}
+
+function onPerimeter(segment, rect) {
+  return segment.y1 === segment.y2
+    ? near(segment.y1, rect.y) || near(segment.y1, rect.y + rect.height)
+    : near(segment.x1, rect.x) || near(segment.x1, rect.x + rect.width);
+}
+
+export function buildGridmapModel(input, world = DEFAULT_WORLDS.landscape) {
+  const data = normaliseGridmapData(input);
+  const totalCells = data.layers.reduce((sum, layer) =>
+    sum + itemsOf(layer).reduce((itemSum, item) => itemSum + cellCount(item), 0), 0);
+  const usableHeight = world.height - world.gutter * (data.layers.length - 1);
+
+  const model = { data, world: { ...world }, layers: [], groups: [], items: [], cells: [] };
+  let layerY = world.y;
+
+  data.layers.forEach((layerInput, layerIndex) => {
+    const sourceItems = itemsOf(layerInput).map((item) => ({ ...item, n: item.cells.length }));
+    const layerRect = {
+      x: world.x,
+      y: layerY,
+      width: world.width,
+      height: usableHeight * weightSum(sourceItems) / totalCells,
+    };
+    const layer = {
+      index: layerIndex,
+      id: layerInput.id,
+      label: layerInput.label,
+      meta: layerInput.meta,
+      ...layerRect,
+      groups: [],
+      items: [],
+    };
+    model.layers.push(layer);
+
+    for (const region of partitionItems(sourceItems, layerRect).regions) {
+      const { id, label, shortLabel, cells, groupId, groupLabel, groupMeta, meta, rect } = region;
+      const item = {
+        index: model.items.length,
+        id,
+        label,
+        shortLabel,
+        meta,
+        layerId: layer.id,
+        layerLabel: layer.label,
+        layerIndex: layer.index,
+        groupId,
+        groupLabel,
+        groupIndex: -1,
+        cellCount: cells.length,
+        ...rect,
+        cells: [],
+      };
+
+      layoutCells(cells, rect.x, rect.y, rect.width, rect.height).forEach((cellRect, cellIndex) => {
+        const source = cells[cellIndex];
+        const cell = {
+          index: model.cells.length,
+          id: source.id,
+          label: source.label,
+          value: source.value,
+          meta: source.meta,
+          layerId: layer.id,
+          layerLabel: layer.label,
+          layerIndex: layer.index,
+          groupId,
+          groupLabel,
+          groupIndex: -1,
+          itemId: item.id,
+          itemLabel: item.label,
+          itemShortLabel: item.shortLabel,
+          itemIndex: item.index,
+          ordinal: cellIndex + 1,
+          ...cellRect,
+          centerX: cellRect.x + cellRect.width / 2,
+          centerY: cellRect.y + cellRect.height / 2,
+        };
+        item.cells.push(cell);
+        model.cells.push(cell);
+      });
+
+      layer.items.push(item);
+      model.items.push(item);
+    }
+
+    for (const groupInput of layerInput.groups) {
+      const items = layer.items.filter((item) => item.groupId === groupInput.id);
+      const group = {
+        index: model.groups.length,
+        uid: `${layer.id}/${groupInput.id}`,
+        id: groupInput.id,
+        label: groupInput.label,
+        meta: groupInput.meta ?? {},
+        layerId: layer.id,
+        layerLabel: layer.label,
+        layerIndex: layer.index,
+        items,
+        bounds: boundsOf(items),
+      };
+      group.outline = regionOutline(items).map((segment) => ({
+        ...segment,
+        betweenGroups: !onPerimeter(segment, layer),
+      }));
+      for (const item of items) {
+        item.groupIndex = group.index;
+        for (const cell of item.cells) cell.groupIndex = group.index;
+      }
+      layer.groups.push(group);
+      model.groups.push(group);
+    }
+
+    layerY += layer.height + world.gutter;
+  });
+
+  const firstCell = model.cells[0];
+  model.cellSide = firstCell ? Math.sqrt(firstCell.width * firstCell.height) : 1;
+  return model;
+}
+
+export function cellAt(model, x, y) {
+  if (!model) return null;
+  for (const item of model.items) {
+    if (x < item.x || x >= item.x + item.width || y < item.y || y >= item.y + item.height) continue;
+    for (const cell of item.cells) {
+      if (x >= cell.x && x < cell.x + cell.width && y >= cell.y && y < cell.y + cell.height) return cell;
+    }
+  }
+  return null;
+}
+
+export function validateGridmapModel(model) {
+  const itemCells = model.items.reduce((sum, item) => sum + item.cells.length, 0);
+  if (itemCells !== model.cells.length) throw new Error('model cell count does not match item cell total');
+  if (model.groups.flatMap((group) => group.items).length !== model.items.length) {
+    throw new Error('each item must belong to exactly one group');
+  }
+  if (!model.cells.every((cell) => model.items[cell.itemIndex]?.cells.includes(cell))) {
+    throw new Error('each cell must belong to exactly one item');
+  }
+  return true;
+}