feat: 3x3 frozen band model - right-frozen columns + simultaneous top/bottom frozen rows (ViewportMgr Phase 4)

[6pac]

Summary

Completes the 3×3 band model. Rebased onto current master (includes the #1229 squash and the #1231/#1232 fixes — the scrollTo paging fix verified intact alongside the band code); supersedes the stacked #1236. Contains the full ViewportMgr series: the #1234 commits replay here identically, so #1234 can be closed in favour of this PR or merged first — either order works. SlickGrid now supports left AND right frozen columns and top AND bottom frozen rows in any combination — up to nine panes — all managed by ViewportMgr, with every legacy configuration byte-identical (proven by the phase 0–3 characterization suites, which run unchanged).

New capabilities (all opt-in via new options; defaults preserve current behaviour exactly)

• frozenRightColumn (count from the right edge — counts survive column reorder/hide, unlike index-based frozenColumn): a right-frozen column band with new *-right-frozen css classes. The historical "right" elements keep their names and become the scrollable middle band. Column-side selection, geometry (band pinned at the right edge, middle band shrinks), row-fragment routing (rowNode grows to 3 entries), band-local cell coordinates, keyboard navigation across the boundary, and Y-scroll following are all implemented and spec-pinned.
• frozenBottomRow (count, usable TOGETHER with frozenRow, which then always means top rows; the legacy frozenBottom flag keeps its exact historical single-band meaning): a bottom-frozen row band (*-bottom-frozen classes) with three-way row routing, geometry (band pinned below the body, above its scrollbar), X-scroll following, and runtime toggling. The shared bottom-frozen × right-frozen corner pane is created by whichever band materializes second.
• Public band API: getFrozenBandCounts() / getFrozenRightStartIndex(); cellrangeselector is migrated onto it, which also fixes its cross-canvas measurement under the new modes and adds correct offsets/clamps for the new bands.
• ViewportMgr extracted to slick.core.ts (registered on the Slick namespace beside DragExtendHandle; contracts in src/models/viewportMgr.interface.ts) — slick.grid.ts ends ~1,500 lines lighter than before the whole refactor, with zero frozen-flag branching outside setFrozenOptions. No consumer impact: core already loads before the grid everywhere.

Hardening

Three adversarial equivalence audits ran during Phase 4 (right-band transitions, bottom-band-off equivalence, init-window binding). Real defects found and fixed by them: stale-band routing/geometry guards after un-freezing, an init-window event double-binding (latent since the right-band milestone), and a dropped disableSelection on init-materialized headers. Known preserved quirks and invariants are documented in the source at their definitions.

Testing

Three new example pages and 25 new band tests across three specs (viewportmgr-right-frozen-band, viewportmgr-bottom-frozen-band, extended viewportmgr-lazy-materialization), covering init-time and runtime materialization, geometry, routing, navigation, and un-freeze restoration. Every commit in the series landed only after the full Cypress suite passed locally (632 tests). Headless-only retries: { runMode: 1 } added to the Cypress config after reproducing a ~1-in-4 machine-level flake on pristine master (three different victim specs across runs; CI here is the authoritative check).

🤖 Generated with Claude Code

[6pac]

Freeze activation options — ViewportMgr refactor (SlickGrid)

Reference for the grid-option surface controlling frozen rows/columns after the
ViewportMgr refactor (branches viewportmgr-phase1 / viewportmgr-phase4,
PRs #1234 / #1236). Companion docs: PLAN-panegrid.md, KNOWN-QUIRKS.md.

Option surface

Option	Kind	Default	Meaning
frozenColumn	legacy, index	-1	Left-frozen columns: freeze columns 0..N inclusive. Semantics unchanged from upstream.
frozenRow	legacy, count	-1	Frozen rows. Always the top band whenever frozenBottomRow is in use; otherwise positioned by frozenBottom.
frozenBottom	legacy flag	false	Positions the single frozenRow band at the bottom instead of the top. Ignored when frozenBottomRow > 0 (it only ever selects the single-band position).
frozenRightColumn	new, count from the right edge	0	Right-frozen column band. A count, not an index — counts stay correct when columns are reordered or hidden (avoids the index-drift problems calculateFrozenColumnIndexById patches for frozenColumn).
frozenBottomRow	new, count	0	Rows frozen at the bottom alongside top rows — the simultaneous top+bottom mode (three row bands).
lazyPanes	new, opt-in	false	Build only the top-left pane/viewport/canvas when nothing is frozen at construction; all other panes materialize on demand. Off by default because it changes the DOM for consumers that style/query the historically ever-present unused panes.

Activation model

• No allow-freeze presets. The originally planned init-time gates
  ("allow freeze left/right/top/bottom", which would have pre-created pane DOM and
  permanently fixed a grid's available freeze modes) were dropped during the
  dynamic-materialization feasibility work (plan §4b): band existence is driven
  directly by the freeze options themselves. Any freeze can be enabled or disabled
  at runtime via setOptions() on any grid; band DOM materializes on first use at
  its canonical position. The vestigial preCreateBands perf hint from the early
  API sketch was never needed and never implemented.
• A default-configured grid is byte-identical to the pre-refactor grid (all six
  classic panes built up front; freeze options show/hide and route).
• The two new bands (frozenRightColumn, frozenBottomRow) are always
  materialize-on-demand regardless of lazyPanes — set them in the constructor
  options or later via setOptions(); either path produces the same DOM.
• Un-freezing hides band panes but keeps them in the DOM (matches the historical
  always-present behaviour; see KNOWN-QUIRKS.md design decision Prevent useless onSelectedRangesChanged events in selectionmodels' setSelectedRanges #9).

Plugin-facing band API (for completeness)

• grid.getFrozenBandCounts() → { frozenLeftCols, frozenRightCols, frozenTopRows, frozenBottomRows } (a copy; zero = band absent)
• grid.getFrozenRightStartIndex() → index of the first right-frozen column, or the column count when the band is off (idx >= result is a safe membership test)

[6pac]

Will investigate ways to reduce the line count tomorrow, but this PR is the start for manual testing.

[ghiscoding]

What I'm worried about in this PR is the very large amount of new lines of code, over 1400 lines of code (loc) as shown below, that is a lot!!! The only thing that we're gaining here is right freeze and also to stop rendering panes that aren't being used (e.g. pane-right or pane-bottom, etc...). If so, 1400 loc for basically just adding right freeze, is just way too much. It would increase the lib size by a lot, we can certainly do better

[6pac]

looking into that, but I think it's worth testing at this point to sanity check the overall usability.

Claude is indicating that it kept a lot of architecture the same way just to maintain byte-identical HTML in thos PR, but we can lose about 600 further lines through a subsequent stage 2 refactor. I'm investigating adding the sticky rows feature as well - I'm interested to see if that would use a lot of the same code.

At the moment I'm not sreally sure how to roll this out though - this PR applies to main and can be merged locally without merging in the main repo, for testing. A further PR could I suppose also be pulled and merged locally on top of the previous merge. Is that workflow OK for you?

[ghiscoding]

I think that considering this is probably going to be released under a major (aka breaking) version, then there's no point in carrying over old code if you can rewrite it in a better way that might change certain flags and behaviours (that's what major versions are for). Like I said a while ago, we can create a branch named "next" or "dev" (based on master) and once accepted merge all your PRs on that next branch so that you can use it until ready to fully release it under a major version (that's what I've done in the past with v4 and v5), then merge back next into master when officially released.

The only PR that could be merged and released under current v5 is the variable row height, I would put more focus on finishing that one. Anything else (freeze/pinning rewrite, sticky columns, drop SortableJS, ...) should be done in a separate next or dev branch and consider that branch to be the future v6 (because all of these features contain some form of breaking changes/behaviors)

looking into that, but I think it's worth testing at this point to sanity check the overall usability.

I did test the UI quickly, that's how I saw that you did stop rendering the pane-right/pane-bottom/... when not displayed (which I agree with). But apart from the right column freeze (which seems a little off in the demo since left columns weren't covering all left space though it becomes ok when grid has lots of columns), that feature alone surely doesn't explain the addition of over 1400 loc

[6pac]

This PR has undergone three stages: 1) wrap the viewport/panes in an object, 2) rework individial viewport related objects (eg, ViewportL, ViewportR, HeaderL, HeaderR, HeaderRowL, HeaderRowR) into an array 3) encapsulate all multi pane concerns into the ViewportMgr object and take the slick.grid.ts code back to what it looked like before the frozen panes change.
This is the prompt for part 3, just to make clear what the motivation was.

---

The primary reason I wanted to do this change was to simplify the code in 'slick.grid.js'. This goal has not been met.

To illustrate what I mean, take the following examples:

SlickGrid-pre-frozen: (in createColumnHeaders())

  $headers.empty();
  $headers.width(getHeadersWidth());

SlickGrid-post-frozen: (in createColumnHeaders())

  $headerL.empty();
  $headerR.empty();

  getHeadersWidth();

  $headerL.width(headersWidthL);
  $headerR.width(headersWidthR);

6pac master: (in createColumnHeaders())

Utils.emptyElement(this._headerL);
Utils.emptyElement(this._headerR);

this.getHeadersWidth();

Utils.width(this._headerL, this.headersWidthL);
Utils.width(this._headerR, this.headersWidthR);

6pac viewportmgr-phase4: (in createColumnHeaders())

Utils.emptyElement(this._headerL);
if (this._headerR) {
  Utils.emptyElement(this._headerR);
}
if (this._viewportMgr.headerRF) {
  Utils.emptyElement(this._viewportMgr.headerRF);
}

this.getHeadersWidth();

Utils.width(this._headerL, this.headersWidthL);
Utils.width(this._headerR, this.headersWidthR);
Utils.width(this._viewportMgr.headerRF, this.headersWidthRF);

The pre-frozen code is simple and says exactly what it does. Then post-frozen, rather that reading the logical flow, you suddenly have to deal with multiple headers etc - and with the LazyPanes option we used the multiple headers may not even be actively used.
The current 6pac code more or less mirrors the post-frozen format, and viewportmgr-phase4 collapses some of the logic into the viewportmgr object, but it doesn't really change it.
What I'd like is for it to read something like:

desired:

  this._viewportMgr.headers.empty();
  this._viewportMgr.headers.width(getHeadersWidth());

This would require wrapping all of the headers and footers into the ViewportMgr object - and that's what I really wanted, a single object that slick.grid.js can manipulate like a single pane that keeps all of the concerns about how many pane/header/footer elements there are and hides them from the grid code.

Another example:

SlickGrid-pre-frozen:

function getFooterRowColumn(columnIdOrIdx) {
  var idx = (typeof columnIdOrIdx === "number" ? columnIdOrIdx : getColumnIndex(columnIdOrIdx));
  var $rtn = $footerRow.children().eq(idx);
  return $rtn && $rtn[0];
}

SlickGrid-pre-frozen:

function getFooterRowColumn(columnIdOrIdx) {
  var idx = (typeof columnIdOrIdx === "number" ? columnIdOrIdx : getColumnIndex(columnIdOrIdx));

  var $footerRowTarget;

  if (hasFrozenColumns()) {
    if (idx <= options.frozenColumn) {
      $footerRowTarget = $footerRowL;
    } else {
      $footerRowTarget = $footerRowR;

      idx -= options.frozenColumn + 1;
    }
  } else {
    $footerRowTarget = $footerRowL;
  }

  var $footer = $footerRowTarget.children().eq(idx);
  return $footer && $footer[0];
}

6pac master:

/**
* Get the Footer Row Column DOM element by its column Id or index
* @param {Number|String} columnIdOrIdx - column Id or index
*/
getFooterRowColumn(columnIdOrIdx: number | string) {
  let idx = (typeof columnIdOrIdx === 'number' ? columnIdOrIdx : this.getColumnIndex(columnIdOrIdx));
  let footerRowTarget: HTMLDivElement;

  if (this.hasFrozenColumns()) {
    if (idx <= this._options.frozenColumn!) {
      footerRowTarget = this._footerRowL;
    } else {
      footerRowTarget = this._footerRowR;

      idx -= this._options.frozenColumn! + 1;
    }
  } else {
    footerRowTarget = this._footerRowL;
  }

  return footerRowTarget.children[idx] as HTMLDivElement;
}

6pac viewportmgr-phase4:

/** 
 * Get the Footer Row Column DOM element by its column Id or index
 * @param {Number|String} columnIdOrIdx - column Id or index
 */
getFooterRowColumn(columnIdOrIdx: number | string) {
  const idx = (typeof columnIdOrIdx === 'number' ? columnIdOrIdx : this.getColumnIndex(columnIdOrIdx));
  const footerRowTarget = this._viewportMgr.bandElementForColumn(idx, this._footerRowL, this._footerRowR,  this._viewportMgr.footerRowRF);

 return footerRowTarget.children[this._viewportMgr.bandLocalColumnIdx(idx)] as HTMLDivElement;

}

desired:

/**
 * Get the Footer Row Column DOM element by its column Id or index
 * @param {Number|String} columnIdOrIdx - column Id or index
 */
getFooterRowColumn(columnIdOrIdx: number | string) {
  const idx = (typeof columnIdOrIdx === 'number' ? columnIdOrIdx : this.getColumnIndex(columnIdOrIdx));
  return this._viewportMgr.getColumnChildren(idx);
}

Report on the feasibility of this, and list the proposed new members of ViewportMgr, and before and after code in slick.grid.ts for each use case in that file. It impacts on both the viewportmgr-phase4 and the m16 plan currently in progress.
Also assess if it would be easier to start from scratch and redo the whole viewportmgr-phase4 PR, or to update and replace the m18 work, or to add it on after m18?