Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Stop frozen table headers flickering on fast scroll (PRD-9328) (#6161)

Andrew Mikofalvyce88def4e405
diff --git a/.changeset/prd-9328-frozen-header-stacking.md b/.changeset/prd-9328-frozen-header-stacking.md
new file mode 100644
index 000000000..3cf75b71f
--- /dev/null
+++ b/.changeset/prd-9328-frozen-header-stacking.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+A table's header row no longer flickers under body rows when a fast scroll freezes it, and the first header cell stays on top when a wide table scrolls sideways.
diff --git a/packages/app/src/editor/extensions/frozen-table-headers.ts b/packages/app/src/editor/extensions/frozen-table-headers.ts
index 2548820ab..fcc018994 100644
--- a/packages/app/src/editor/extensions/frozen-table-headers.ts
+++ b/packages/app/src/editor/extensions/frozen-table-headers.ts
@@ -60,8 +60,6 @@ function resetHeaderCells(firstRow: HTMLTableRowElement): void {
}
}
-const cellZIndex = (cell: HTMLTableCellElement): string => (cell.cellIndex === 0 ? '3' : '2');
-
export function buildShiftKeyframes(range: FreezeRange, scrollMax: number): Keyframe[] {
return buildFreezeKeyframes(range, scrollMax, (shift) => ({
transform: `translateY(${shift}px)`,
@@ -126,12 +124,12 @@ function buildBoundaryFlipKeyframes(
];
}
-function buildChromeKeyframes(range: FreezeRange, scrollMax: number, zIndex: string): Keyframe[] {
+function buildChromeKeyframes(range: FreezeRange, scrollMax: number): Keyframe[] {
return buildBoundaryFlipKeyframes(
range,
scrollMax,
- { zIndex: 'auto', boxShadow: 'none' },
- { zIndex, boxShadow: FROZEN_SHADOW },
+ { boxShadow: 'none' },
+ { boxShadow: FROZEN_SHADOW },
);
}
@@ -145,15 +143,14 @@ export function applyScrollDrivenFreeze(
range: FreezeRange,
scrollMax: number,
): void {
- const zIndex = cellZIndex(cell);
- const key = `sd|${range.startOffset}|${range.maxShift}|${scrollMax}|${zIndex}`;
+ const key = `sd|${range.startOffset}|${range.maxShift}|${scrollMax}`;
const prev = appliedFreezes.get(cell);
if (prev?.key === key) return;
if (prev) for (const animation of prev.animations) animation.cancel();
const base: ScrollDrivenAnimationOptions = { timeline, fill: 'both', easing: 'linear' };
const transformAnimation = cell.animate(buildShiftKeyframes(range, scrollMax), base);
- const chromeAnimation = cell.animate(buildChromeKeyframes(range, scrollMax, zIndex), base);
+ const chromeAnimation = cell.animate(buildChromeKeyframes(range, scrollMax), base);
const occluderAnimation = cell.animate(buildOccluderKeyframes(range, scrollMax), {
...base,
pseudoElement: '::before',
@@ -180,13 +177,12 @@ export function anchorScrollDrivenStartTime(animation: Animation): void {
}
function applyInstantFreeze(cell: HTMLTableCellElement, shift: number): void {
- const zIndex = cellZIndex(cell);
- const key = `in|${shift}|${zIndex}`;
+ const key = `in|${shift}`;
const prev = appliedFreezes.get(cell);
if (prev?.key === key) return;
if (prev) for (const animation of prev.animations) animation.cancel();
const animation = cell.animate(
- [{ transform: `translateY(${shift}px)`, zIndex, boxShadow: FROZEN_SHADOW }],
+ [{ transform: `translateY(${shift}px)`, boxShadow: FROZEN_SHADOW }],
{ duration: 0, fill: 'forwards' },
);
const occluderAnimation = cell.animate([{ opacity: '1' }], {
diff --git a/packages/app/src/globals.css b/packages/app/src/globals.css
index ddcfc9526..ef3e5d730 100644
--- a/packages/app/src/globals.css
+++ b/packages/app/src/globals.css
@@ -2421,13 +2421,38 @@
background-color: var(--background);
}
-/* Corner cell (first column + header row) must clear both frozen row layer and
- sticky column layer when both are active simultaneously. */
+/* The header row stacks above body rows at every scroll position. The freeze
+ translates it with a compositor-driven animation; a stacking flip at the
+ freeze boundary would land on the main thread, frames behind the transform,
+ leaving body rows painted over the moving header during a fast scroll. */
+.ProseMirror .tableWrapper > table > tbody > tr:first-child > th {
+ z-index: 2;
+}
+
+/* First-column header cells in body rows (header-column tables) sit above the
+ sticky body column. */
.ProseMirror .tableWrapper > table > tbody > tr > th:first-child {
background-color: var(--muted);
z-index: 3;
}
+/* A header cell's resize handle overhangs its right border; raise the cell
+ holding it so the next header cell does not cover the overhang. */
+.ProseMirror
+ .tableWrapper
+ > table
+ > tbody
+ > tr:first-child
+ > th:not(:first-child):has(> .column-resize-handle) {
+ z-index: 3;
+}
+
+/* Corner cell (first column + header row) clears the header row, a raised
+ resize-handle cell and the sticky column, frozen or not. */
+.ProseMirror .tableWrapper > table > tbody > tr:first-child > th:first-child {
+ z-index: 4;
+}
+
/* Occluder above the frozen header (frozen-table-headers.ts): scrolled-past
rows must not show in the translucent toolbar-fade slot above the pinned
header. An opaque block riding each header cell's composited layer tracks
diff --git a/packages/app/tests/stress/frozen-table-headers.e2e.ts b/packages/app/tests/stress/frozen-table-headers.e2e.ts
index 0095f1462..959b45eca 100644
--- a/packages/app/tests/stress/frozen-table-headers.e2e.ts
+++ b/packages/app/tests/stress/frozen-table-headers.e2e.ts
@@ -84,6 +84,24 @@ ${Array.from({ length: 28 }, (_, i) => `Appendix paragraph ${i + 1} below the ta
const SCROLL_SELECTOR = '[data-testid="editor-scroll-container"]';
const TOOLBAR_HEIGHT = 56;
+async function hoverHeaderBorder(
+ page: Parameters<typeof test>[1]['page'],
+ colIndex: number,
+): Promise<{ x: number; y: number }> {
+ const border = await page.evaluate((idx) => {
+ const row = document
+ .querySelector('.ProseMirror .tableWrapper > table > tbody')
+ ?.querySelector('tr') as HTMLTableRowElement | null;
+ const r = row?.cells[idx]?.getBoundingClientRect();
+ return r ? { x: r.right - 1, y: r.top + r.height / 2 } : null;
+ }, colIndex);
+ if (!border) throw new Error(`no header cell at index ${colIndex}`);
+ await page.mouse.move(border.x, border.y);
+ await page.mouse.move(border.x, border.y);
+ await page.locator('.column-resize-handle').first().waitFor({ state: 'attached' });
+ return border;
+}
+
async function scanSlotPixels(page: Parameters<typeof test>[1]['page']): Promise<number> {
const band = await page.evaluate(() => {
const table = document.querySelector('.ProseMirror .tableWrapper > table') as HTMLElement;
@@ -296,6 +314,29 @@ test('no freeze before the table reaches the toolbar', async ({
return cell ? getComputedStyle(cell, '::before').opacity : '';
});
expect(occluderOpacity).toBe('0');
+ const unfrozenStacking = await page.evaluate(() => {
+ const row = document.querySelector(
+ '.ProseMirror .tableWrapper > table > tbody > tr',
+ ) as HTMLTableRowElement | null;
+ if (!row) return null;
+ return {
+ cornerZ: getComputedStyle(row.cells[0]).zIndex,
+ headerZ: getComputedStyle(row.cells[1]).zIndex,
+ };
+ });
+ expect(unfrozenStacking).toEqual({ cornerZ: '4', headerZ: '2' });
+ await hoverHeaderBorder(page, 1);
+ const resizeStacking = await page.evaluate(() => {
+ const row = document.querySelector(
+ '.ProseMirror .tableWrapper > table > tbody > tr',
+ ) as HTMLTableRowElement;
+ return {
+ handleInHovered: row.cells[1].querySelector(':scope > .column-resize-handle') !== null,
+ hoveredZ: getComputedStyle(row.cells[1]).zIndex,
+ nextZ: getComputedStyle(row.cells[2]).zIndex,
+ };
+ });
+ expect(resizeStacking).toEqual({ handleInHovered: true, hoveredZ: '3', nextZ: '2' });
await page.screenshot({ path: testInfo.outputPath('unscrolled.png') });
});
@@ -375,19 +416,7 @@ test('first column stays pinned during horizontal scroll after column resize', a
await waitForQuiescence(page, SCROLL_SELECTOR);
for (const colIndex of [5, 4, 3, 2, 1, 0]) {
- const border = await page.evaluate((idx) => {
- const row = document
- .querySelector('.ProseMirror .tableWrapper > table > tbody')
- ?.querySelector('tr') as HTMLTableRowElement | null;
- const cell = row?.cells[idx];
- if (!cell) return null;
- const r = cell.getBoundingClientRect();
- return { x: r.right - 1, y: r.top + r.height / 2 };
- }, colIndex);
- if (!border) throw new Error(`no header cell at index ${colIndex}`);
- await page.mouse.move(border.x, border.y);
- await page.mouse.move(border.x, border.y);
- await page.locator('.column-resize-handle').first().waitFor({ state: 'attached' });
+ const border = await hoverHeaderBorder(page, colIndex);
await page.mouse.down();
await page.mouse.move(border.x + 70, border.y, { steps: 6 });
await page.mouse.up();
@@ -469,19 +498,7 @@ test('virtualized long doc: both freezes hold on a 200-row table', async ({
await twoFrames(page);
await twoFrames(page);
for (const colIndex of [4, 3, 2, 1, 0]) {
- const border = await page.evaluate((idx) => {
- const row = document
- .querySelector('.ProseMirror .tableWrapper > table > tbody')
- ?.querySelector('tr') as HTMLTableRowElement | null;
- const cell = row?.cells[idx];
- if (!cell) return null;
- const r = cell.getBoundingClientRect();
- return { x: r.right - 1, y: r.top + r.height / 2 };
- }, colIndex);
- if (!border) throw new Error(`no header cell at index ${colIndex}`);
- await page.mouse.move(border.x, border.y);
- await page.mouse.move(border.x, border.y);
- await page.locator('.column-resize-handle').first().waitFor({ state: 'attached' });
+ const border = await hoverHeaderBorder(page, colIndex);
await page.mouse.down();
await page.mouse.move(border.x + 80, border.y, { steps: 6 });
await page.mouse.up();
@@ -516,7 +533,7 @@ test('virtualized long doc: both freezes hold on a 200-row table', async ({
expect(combined?.overflow ?? 0).toBeGreaterThan(100);
expect(combined?.stickyDriftPx ?? 99).toBeLessThan(2);
expect(combined?.neighborShiftPx ?? 0).toBeGreaterThan(100);
- expect(combined?.cornerZ).toBe('3');
+ expect(combined?.cornerZ).toBe('4');
expect(combined?.headerZ).toBe('2');
await twoFrames(page);
await page.screenshot({ path: testInfo.outputPath('virtualized-combined.png') });