OpenParable
Skip to content
← Back to skills

Coordinate Systems

Testing & Quality
coordinate-systems

Coordinate Systems is an Agent Skill for testing & quality published in the handsontable/handsontable repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when working with row or column indexes in Handsontable - translating between physical, visual, and renderable coordinates, using IndexMapper, or debugging index-related bugs where rows or columns appear in wrong positions

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/handsontable/handsontable/blob/HEAD/.claude/skills/coordinate-systems/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/coordinate-systems, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Coordinate Systems

Handsontable uses three coordinate systems because the position of a row or column can differ depending on whether you are looking at the raw data, the logical grid after filtering/trimming, or the actual DOM. Mixing them up is one of the most common sources of bugs.

The three systems

SystemWhat it representsKey behavior
PhysicalPosition in the source data array (0 to N)Never changes regardless of filtering, sorting, trimming, hiding, or moving. Always 0 to N.
VisualPosition in what Handsontable has processedChanges when data is filtered, sorted, trimmed, or columns/rows are moved. Hidden columns/rows still have visual indexes - hiding does not remove from visual space.
RenderablePosition in the DOMOnly matters for Walkontable. Very rarely used in public API and Handsontable.

The public Handsontable API mainly uses visual indexes, sometimes physical, and very rarely renderable (if any).

In Walkontable (the rendering engine), the data is already filtered, sorted, trimmed (etc.) by Handsontable, so Walkontable renders it as-is from 0 to N. Walkontable also uses "source index" and "render index" internally for virtualization - calculating what needs to be rendered at the current scroll position.

HidingMap vs TrimmingMap

  • HidingMap - The index stays in the DataMap (visual space) but is not rendered in the DOM. Used by HiddenColumns and HiddenRows. Important: hidden columns/rows still have visual indexes. The data is still accessible via getDataAtCell() with visual coordinates.
  • TrimmingMap - The index is removed from the DataMap entirely. Used by TrimRows and Filters. Trimmed rows do not exist in visual space at all.

IndexMapper API

Access via hot.rowIndexMapper or hot.columnIndexMapper. Key methods:

// Translate between systems
mapper.getPhysicalFromVisualIndex(visualIndex)
mapper.getVisualFromPhysicalIndex(physicalIndex)
mapper.getPhysicalFromRenderableIndex(renderableIndex)
mapper.getRenderableFromVisualIndex(visualIndex)

// Register a new map
mapper.createAndRegisterIndexMap(name, type, initialValue)
// type: 'hiding' | 'trimming'

When to use which coordinate

You are doingUse
Reading or writing source dataPhysical
Working with user-facing row/column positions, selection, or getDataAtCol()Visual
Accessing DOM nodes, cell elements, or Walkontable APIsRenderable
Storing persistent state (e.g., sorting order, filter conditions)Physical

Common gotcha: Filters + ManualColumnMove

The conditionCollection and conditionUpdateObserver in the Filters plugin operate on physical indexes, while getDataAtCol() requires visual indexes. When manualColumnMove is active, physical and visual column order diverge. Always convert with getVisualFromPhysicalIndex() / getPhysicalFromVisualIndex() before crossing the boundary.

Quick plugin reference

PluginMap typeCoordinate it manages
HiddenColumns / HiddenRowsHidingMapVisual to renderable
TrimRows / FiltersTrimmingMapPhysical to visual
ManualColumnMove / ColumnSortingIndexesSequencePhysical to visual

Source files

Implementation lives in src/translations/ - see indexMapper.ts, maps/, and mapCollections/. For the deep subsystem reference (map types, translation methods, cache, observers, registration lifecycle), see handsontable/.ai/INDEX-MAPPING.md; for wider system context, handsontable/.ai/ARCHITECTURE.md.