Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Stop rebuilding the frozen table header mid-scroll (PRD-9328) (#6225)

Andrew Mikofalvy23c541b131e0
diff --git a/.changeset/prd-9328-frozen-header-stacking.md b/.changeset/prd-9328-frozen-header-stacking.md
index 3cf75b71f..1500472b1 100644
--- a/.changeset/prd-9328-frozen-header-stacking.md
+++ b/.changeset/prd-9328-frozen-header-stacking.md
@@ -2,4 +2,4 @@
"@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.
+A table's header row no longer jumps or slips under body rows while 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.test.ts b/packages/app/src/editor/extensions/frozen-table-headers.test.ts
index a442bf73f..2c851113b 100644
--- a/packages/app/src/editor/extensions/frozen-table-headers.test.ts
+++ b/packages/app/src/editor/extensions/frozen-table-headers.test.ts
@@ -1,9 +1,10 @@
import { afterEach, describe, expect, it, vi } from 'vitest';
import {
anchorScrollDrivenStartTime,
- applyScrollDrivenFreeze,
+ applyViewTimelineFreeze,
buildShiftKeyframes,
computeFreezeRange,
+ computeWrapperFreeze,
} from './frozen-table-headers.ts';
describe('computeFreezeRange (scroll-driven animation ranges)', () => {
@@ -46,6 +47,71 @@ describe('computeFreezeRange (scroll-driven animation ranges)', () => {
});
});
+describe('computeWrapperFreeze (view-timeline cover ranges)', () => {
+ it('returns null for a single-row table', () => {
+ expect(computeWrapperFreeze(0, 40, 0, 40, 40, 700)).toBeNull();
+ });
+
+ it('spans the cover range: scrollport plus wrapper height', () => {
+ const freeze = computeWrapperFreeze(200, 1000, 200, 1000, 40, 700);
+ expect(freeze).toEqual({
+ range: { startOffset: 700, endOffset: 1660, maxShift: 960 },
+ timelineLength: 1700,
+ });
+ });
+
+ it('offsets the ramp by the table position inside its wrapper', () => {
+ const freeze = computeWrapperFreeze(200, 1016, 208, 1000, 40, 700);
+ expect(freeze?.range.startOffset).toBe(708);
+ });
+
+ it('agrees with the per-frame shift formula at every scroll position', () => {
+ const containerTop = 0;
+ const toolbar = 56;
+ const clientHeight = 756;
+ const wrapperDocTop = 1200;
+ const tableDocTop = 1208;
+ const wrapperHeight = 1016;
+ const tableHeight = 1000;
+ const headerHeight = 40;
+ const freeze = computeWrapperFreeze(
+ wrapperDocTop,
+ wrapperHeight,
+ tableDocTop,
+ tableHeight,
+ headerHeight,
+ clientHeight - toolbar,
+ );
+ if (!freeze) throw new Error('expected a freeze');
+ const coverStart = wrapperDocTop - clientHeight;
+ for (const scrollTop of [0, 444, 1144, 1152, 1153, 1600, 2112, 2500, 4000]) {
+ const coverScroll = scrollTop - coverStart;
+ const animShift = Math.max(
+ 0,
+ Math.min(coverScroll - freeze.range.startOffset, freeze.range.maxShift),
+ );
+ const tableTop = tableDocTop - scrollTop;
+ const expected = Math.max(
+ 0,
+ Math.min(containerTop + toolbar - tableTop, tableHeight - headerHeight),
+ );
+ expect(animShift).toBe(expected);
+ }
+ });
+
+ it('is unchanged when the table only moves in the viewport', () => {
+ const atTop = computeWrapperFreeze(1200, 1016, 1208, 1000, 40, 700);
+ const scrolled = computeWrapperFreeze(1200 - 900, 1016, 1208 - 900, 1000, 40, 700);
+ expect(scrolled).toEqual(atTop);
+ });
+
+ it('absorbs sub-layout-unit noise in measured rects', () => {
+ const exact = computeWrapperFreeze(300, 1016, 308, 1000, 40, 700);
+ const noisy = computeWrapperFreeze(300.0041, 1016.0003, 308.0049, 999.9998, 40.0002, 699.9996);
+ expect(noisy).toEqual(exact);
+ });
+});
+
describe('buildShiftKeyframes', () => {
const ty = (k: Keyframe): number =>
Number(/translateY\((-?[\d.]+)px\)/.exec(String(k.transform))?.[1]);
@@ -114,7 +180,7 @@ describe('anchorScrollDrivenStartTime (deletion guard, not browser-rung coverage
});
});
-describe('applyScrollDrivenFreeze (every animation it creates is anchored)', () => {
+describe('applyViewTimelineFreeze (every animation it creates is anchored)', () => {
const realCss = (globalThis as { CSS?: unknown }).CSS;
afterEach(() => {
@@ -137,13 +203,33 @@ describe('applyScrollDrivenFreeze (every animation it creates is anchored)', ()
},
} as unknown as HTMLTableCellElement;
- applyScrollDrivenFreeze(
- cell,
- {} as AnimationTimeline,
- { startOffset: 100, endOffset: 1000, maxShift: 900 },
- 2_000,
- );
+ applyViewTimelineFreeze(cell, {} as AnimationTimeline, {
+ range: { startOffset: 100, endOffset: 1000, maxShift: 900 },
+ timelineLength: 2_000,
+ });
expect(anchored).toEqual([{ percent: 0 }, { percent: 0 }, { percent: 0 }]);
});
+
+ it('keeps its animations when the table only moves in the viewport', () => {
+ (globalThis as { CSS?: unknown }).CSS = { percent: (value: number) => ({ percent: value }) };
+ let created = 0;
+ const cell = {
+ animate: () => {
+ created++;
+ return { cancel: () => {}, set startTime(_value: unknown) {} } as unknown as Animation;
+ },
+ } as unknown as HTMLTableCellElement;
+ const timeline = {} as AnimationTimeline;
+ const freezeAt = (wrapperTop: number) =>
+ computeWrapperFreeze(wrapperTop, 1016, wrapperTop + 8, 1000, 40, 700);
+
+ for (const wrapperTop of [1200, 300, -400]) {
+ const freeze = freezeAt(wrapperTop);
+ if (!freeze) throw new Error('expected a freeze');
+ applyViewTimelineFreeze(cell, timeline, freeze);
+ }
+
+ expect(created).toBe(3);
+ });
});
diff --git a/packages/app/src/editor/extensions/frozen-table-headers.ts b/packages/app/src/editor/extensions/frozen-table-headers.ts
index bed0a0f72..3e3c63ad9 100644
--- a/packages/app/src/editor/extensions/frozen-table-headers.ts
+++ b/packages/app/src/editor/extensions/frozen-table-headers.ts
@@ -8,14 +8,19 @@ const FROZEN_SHADOW = '0 2px 4px rgba(0, 0, 0, 0.08)';
const DRIFT_RECOMPUTE_MS = 150;
-interface ScrollTimelineOptions {
- source: Element | null;
+interface ViewTimelineOptions {
+ subject: Element;
axis?: 'block' | 'inline' | 'x' | 'y';
+ inset?: CSSNumericValue[];
}
-type ScrollTimelineConstructor = new (options: ScrollTimelineOptions) => AnimationTimeline;
+interface ViewTimelineLike extends AnimationTimeline {
+ readonly source: Element | null;
+}
+type ViewTimelineConstructor = new (options: ViewTimelineOptions) => ViewTimelineLike;
+
+const ViewTimelineImpl = (globalThis as { ViewTimeline?: ViewTimelineConstructor }).ViewTimeline;
-const ScrollTimelineImpl = (globalThis as { ScrollTimeline?: ScrollTimelineConstructor })
- .ScrollTimeline;
+let viewTimelinesUsable = Boolean(ViewTimelineImpl);
interface ScrollDrivenAnimationOptions extends KeyframeAnimationOptions {
timeline?: AnimationTimeline | null;
@@ -40,8 +45,35 @@ export function computeFreezeRange(
return { startOffset, endOffset: startOffset + maxShift, maxShift };
}
+export interface WrapperFreeze {
+ range: FreezeRange;
+ timelineLength: number;
+}
+
+const toLayoutUnit = (px: number): number => Math.round(px * 64) / 64;
+
+export function computeWrapperFreeze(
+ wrapperTop: number,
+ wrapperHeight: number,
+ tableTop: number,
+ tableHeight: number,
+ headerHeight: number,
+ scrollportHeight: number,
+): WrapperFreeze | null {
+ const maxShift = toLayoutUnit(tableHeight - headerHeight);
+ const scrollport = toLayoutUnit(scrollportHeight);
+ const wrapper = toLayoutUnit(wrapperHeight);
+ if (maxShift <= 0 || !(wrapper > 0) || !(scrollport > 0)) return null;
+ const startOffset = scrollport + toLayoutUnit(tableTop - wrapperTop);
+ return {
+ range: { startOffset, endOffset: startOffset + maxShift, maxShift },
+ timelineLength: scrollport + wrapper,
+ };
+}
+
interface AppliedFreeze {
key: string;
+ timeline?: AnimationTimeline;
animations: Animation[];
}
@@ -49,6 +81,8 @@ const appliedFreezes = new WeakMap<HTMLTableCellElement, AppliedFreeze>();
const skippedChunks = new WeakSet<Element>();
+const wrapperTimelines = new WeakMap<HTMLElement, { inset: number; timeline: ViewTimelineLike }>();
+
function cancelFreeze(cell: HTMLTableCellElement): void {
const prev = appliedFreezes.get(cell);
if (!prev) return;
@@ -62,18 +96,18 @@ function resetHeaderCells(firstRow: HTMLTableRowElement): void {
}
}
-export function buildShiftKeyframes(range: FreezeRange, scrollMax: number): Keyframe[] {
- return buildFreezeKeyframes(range, scrollMax, (shift) => ({
+export function buildShiftKeyframes(range: FreezeRange, timelineLength: number): Keyframe[] {
+ return buildFreezeKeyframes(range, timelineLength, (shift) => ({
transform: `translateY(${shift}px)`,
}));
}
function buildFreezeKeyframes(
range: FreezeRange,
- scrollMax: number,
+ timelineLength: number,
toProps: (shiftPx: number) => Omit<Keyframe, 'offset'>,
): Keyframe[] {
- if (!(scrollMax > 0)) {
+ if (!(timelineLength > 0)) {
return [
{ offset: 0, ...toProps(0) },
{ offset: 1, ...toProps(0) },
@@ -83,30 +117,30 @@ function buildFreezeKeyframes(
Math.max(0, Math.min(scroll - range.startOffset, range.maxShift));
const breakpoints = Array.from(
new Set(
- [0, range.startOffset / scrollMax, range.endOffset / scrollMax, 1].map((o) =>
+ [0, range.startOffset / timelineLength, range.endOffset / timelineLength, 1].map((o) =>
Math.max(0, Math.min(o, 1)),
),
),
).sort((a, b) => a - b);
return breakpoints.map((offset) => ({
offset,
- ...toProps(shiftAt(offset * scrollMax)),
+ ...toProps(shiftAt(offset * timelineLength)),
}));
}
function buildBoundaryFlipKeyframes(
range: FreezeRange,
- scrollMax: number,
+ timelineLength: number,
pre: Omit<Keyframe, 'offset'>,
post: Omit<Keyframe, 'offset'>,
): Keyframe[] {
- if (!(scrollMax > 0)) {
+ if (!(timelineLength > 0)) {
return [
{ ...pre, offset: 0 },
{ ...pre, offset: 1 },
];
}
- const flip = range.startOffset / scrollMax;
+ const flip = range.startOffset / timelineLength;
if (flip <= 0)
return [
{ ...post, offset: 0 },
@@ -117,7 +151,7 @@ function buildBoundaryFlipKeyframes(
{ ...pre, offset: 0 },
{ ...pre, offset: 1 },
];
- const flipEnd = Math.min(flip + 1 / scrollMax, 1);
+ const flipEnd = Math.min(flip + 1 / timelineLength, 1);
return [
{ ...pre, offset: 0 },
{ ...pre, offset: flip },
@@ -126,40 +160,39 @@ function buildBoundaryFlipKeyframes(
];
}
-function buildChromeKeyframes(range: FreezeRange, scrollMax: number): Keyframe[] {
+function buildChromeKeyframes(range: FreezeRange, timelineLength: number): Keyframe[] {
return buildBoundaryFlipKeyframes(
range,
- scrollMax,
+ timelineLength,
{ boxShadow: 'none' },
{ boxShadow: FROZEN_SHADOW },
);
}
-function buildOccluderKeyframes(range: FreezeRange, scrollMax: number): Keyframe[] {
- return buildBoundaryFlipKeyframes(range, scrollMax, { opacity: '0' }, { opacity: '1' });
+function buildOccluderKeyframes(range: FreezeRange, timelineLength: number): Keyframe[] {
+ return buildBoundaryFlipKeyframes(range, timelineLength, { opacity: '0' }, { opacity: '1' });
}
-export function applyScrollDrivenFreeze(
+export function applyViewTimelineFreeze(
cell: HTMLTableCellElement,
timeline: AnimationTimeline,
- range: FreezeRange,
- scrollMax: number,
+ { range, timelineLength }: WrapperFreeze,
): void {
- const key = `sd|${range.startOffset}|${range.maxShift}|${scrollMax}`;
+ const key = `vt|${range.startOffset}|${range.maxShift}|${timelineLength}`;
const prev = appliedFreezes.get(cell);
- if (prev?.key === key) return;
+ if (prev?.key === key && prev.timeline === timeline) 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), base);
- const occluderAnimation = cell.animate(buildOccluderKeyframes(range, scrollMax), {
+ const transformAnimation = cell.animate(buildShiftKeyframes(range, timelineLength), base);
+ const chromeAnimation = cell.animate(buildChromeKeyframes(range, timelineLength), base);
+ const occluderAnimation = cell.animate(buildOccluderKeyframes(range, timelineLength), {
...base,
pseudoElement: '::before',
});
const animations = [transformAnimation, chromeAnimation, occluderAnimation];
for (const animation of animations) anchorScrollDrivenStartTime(animation);
- appliedFreezes.set(cell, { key, animations });
+ appliedFreezes.set(cell, { key, timeline, animations });
}
let scrollDrivenStartTimeRejectionWarned = false;
@@ -195,8 +228,47 @@ function applyInstantFreeze(cell: HTMLTableCellElement, shift: number): void {
appliedFreezes.set(cell, { key, animations: [animation, occluderAnimation] });
}
+let viewTimelineSourceMismatchWarned = false;
+
+function wrapperTimeline(wrapper: HTMLElement, scrollEl: HTMLElement): ViewTimelineLike | null {
+ if (!ViewTimelineImpl || !viewTimelinesUsable) return null;
+ const inset = editorToolbarOverlapPx();
+ const cached = wrapperTimelines.get(wrapper);
+ if (cached?.inset === inset) return cached.timeline;
+ let timeline: ViewTimelineLike;
+ try {
+ timeline = new ViewTimelineImpl({
+ subject: wrapper,
+ axis: 'block',
+ inset: [CSS.px(inset), CSS.px(0)],
+ });
+ } catch (error) {
+ viewTimelinesUsable = false;
+ if (import.meta.env.DEV) {
+ console.warn(
+ '[frozen-table-headers] ViewTimeline construction rejected; table headers fall back to scroll-event freezing',
+ error,
+ );
+ }
+ return null;
+ }
+ if (timeline.source !== scrollEl) {
+ if (import.meta.env.DEV && !viewTimelineSourceMismatchWarned) {
+ viewTimelineSourceMismatchWarned = true;
+ console.warn(
+ '[frozen-table-headers] a table wrapper resolves to a scroll container other than editor-scroll-container; its header will not freeze',
+ );
+ }
+ return null;
+ }
+ wrapperTimelines.set(wrapper, { inset, timeline });
+ return timeline;
+}
+
interface MeasuredHeader {
firstRow: HTMLTableRowElement;
+ wrapper: HTMLElement;
+ wrapperRect: DOMRect;
tableRect: DOMRect;
headerHeight: number;
}
@@ -204,27 +276,51 @@ interface MeasuredHeader {
function computeAndApplyFrozenHeaders(
scrollEl: HTMLElement,
editorDom: HTMLElement,
- timeline: AnimationTimeline | null,
isRenderingSkipped: (table: HTMLTableElement) => boolean,
): void {
const containerTop = scrollEl.getBoundingClientRect().top;
const scrollTop = scrollEl.scrollTop;
- const scrollMax = scrollEl.scrollHeight - scrollEl.clientHeight;
+ const scrollportHeight = scrollEl.clientHeight - editorToolbarOverlapPx();
const measured: MeasuredHeader[] = [];
for (const table of editorDom.querySelectorAll<HTMLTableElement>('.tableWrapper > table')) {
+ const wrapper = table.parentElement;
const firstRow = table.querySelector('tbody')?.rows[0];
- if (!firstRow || !Array.from(firstRow.cells).some((c) => c.tagName === 'TH')) {
+ if (!wrapper || !firstRow || !Array.from(firstRow.cells).some((c) => c.tagName === 'TH')) {
continue;
}
if (isRenderingSkipped(table)) continue;
measured.push({
firstRow,
+ wrapper,
+ wrapperRect: wrapper.getBoundingClientRect(),
tableRect: table.getBoundingClientRect(),
headerHeight: firstRow.getBoundingClientRect().height,
});
}
- for (const { firstRow, tableRect, headerHeight } of measured) {
+ for (const { firstRow, wrapper, wrapperRect, tableRect, headerHeight } of measured) {
+ const cells = Array.from(firstRow.cells) as HTMLTableCellElement[];
+
+ if (viewTimelinesUsable) {
+ const freeze = computeWrapperFreeze(
+ wrapperRect.top,
+ wrapperRect.height,
+ tableRect.top,
+ tableRect.height,
+ headerHeight,
+ scrollportHeight,
+ );
+ const timeline = freeze ? wrapperTimeline(wrapper, scrollEl) : null;
+ if (freeze && timeline) {
+ for (const cell of cells) applyViewTimelineFreeze(cell, timeline, freeze);
+ continue;
+ }
+ if (viewTimelinesUsable) {
+ resetHeaderCells(firstRow);
+ continue;
+ }
+ }
+
const range = computeFreezeRange(
scrollTop,
containerTop,
@@ -232,31 +328,12 @@ function computeAndApplyFrozenHeaders(
tableRect.height,
headerHeight,
);
-
- if (!range) {
- resetHeaderCells(firstRow);
- continue;
- }
-
- if (timeline) {
- if (scrollMax <= 0) {
- resetHeaderCells(firstRow);
- continue;
- }
- for (const cell of Array.from(firstRow.cells) as HTMLTableCellElement[]) {
- applyScrollDrivenFreeze(cell, timeline, range, scrollMax);
- }
- continue;
- }
-
- const shift = Math.max(0, Math.min(scrollTop - range.startOffset, range.maxShift));
+ const shift = range ? Math.max(0, Math.min(scrollTop - range.startOffset, range.maxShift)) : 0;
if (shift <= 0 || tableRect.bottom <= containerTop + editorToolbarOverlapPx()) {
resetHeaderCells(firstRow);
continue;
}
- for (const cell of Array.from(firstRow.cells) as HTMLTableCellElement[]) {
- applyInstantFreeze(cell, shift);
- }
+ for (const cell of cells) applyInstantFreeze(cell, shift);
}
}
@@ -270,7 +347,6 @@ export const FrozenTableHeaders = Extension.create({
view(editorView) {
let scrollEl: HTMLElement | null = null;
- let timeline: AnimationTimeline | null = null;
let rafId: number | null = null;
let driftTimer: ReturnType<typeof setTimeout> | null = null;
let resizeObserver: ResizeObserver | null = null;
@@ -286,7 +362,7 @@ export const FrozenTableHeaders = Extension.create({
const run = (): void => {
if (destroyed || !scrollEl) return;
- computeAndApplyFrozenHeaders(scrollEl, editorDom, timeline, isRenderingSkipped);
+ computeAndApplyFrozenHeaders(scrollEl, editorDom, isRenderingSkipped);
};
const scheduleRun = (): void => {
@@ -312,7 +388,7 @@ export const FrozenTableHeaders = Extension.create({
});
const onScroll = (): void => {
- if (timeline) {
+ if (viewTimelinesUsable) {
if (driftTimer == null) scheduleRun();
if (driftTimer != null) clearTimeout(driftTimer);
driftTimer = setTimeout(() => {
@@ -332,13 +408,6 @@ export const FrozenTableHeaders = Extension.create({
'[frozen-table-headers] editor-scroll-container not found; table headers will not freeze',
);
}
- if (scrollEl && ScrollTimelineImpl) {
- try {
- timeline = new ScrollTimelineImpl({ source: scrollEl, axis: 'block' });
- } catch {
- timeline = null;
- }
- }
scrollEl?.addEventListener('scroll', onScroll, { passive: true });
if (scrollEl && typeof ResizeObserver !== 'undefined') {
resizeObserver = new ResizeObserver(scheduleRun);
diff --git a/packages/app/tests/stress/frozen-table-headers.e2e.ts b/packages/app/tests/stress/frozen-table-headers.e2e.ts
index faf93d388..feeed5251 100644
--- a/packages/app/tests/stress/frozen-table-headers.e2e.ts
+++ b/packages/app/tests/stress/frozen-table-headers.e2e.ts
@@ -415,6 +415,66 @@ test('header row pins below the toolbar on mid-table scroll', async ({
await page.screenshot({ path: testInfo.outputPath('frozen-mid.png') });
});
+test('a document height change keeps the frozen header on its existing animations', async ({
+ page,
+ api,
+ workerServer,
+}) => {
+ await api.seedDocs([{ name: 'frozen-hdr-long-grow', markdown: LONG_TABLE_MARKDOWN }]);
+ await page.goto(`${workerServer.baseURL}/#/frozen-hdr-long-grow`);
+ await waitForActiveProviderSynced(page);
+ await page.locator('table').first().waitFor({ state: 'visible' });
+ await waitForQuiescence(page, SCROLL_SELECTOR);
+ const before = await scrollAndReadFreeze(page, 260);
+ expect(before.frozen).toBe(true);
+
+ const scrollHeightGrowth = await page.evaluate(async (sel) => {
+ const scrollEl = document.querySelector(sel) as HTMLElement;
+ const cells = Array.from(
+ (
+ document.querySelector(
+ '.ProseMirror .tableWrapper > table > tbody tr',
+ ) as HTMLTableRowElement
+ ).cells,
+ );
+ (window as unknown as { __okHeaderAnimations?: Animation[][] }).__okHeaderAnimations =
+ cells.map((cell) => cell.getAnimations({ subtree: true }));
+ const heightBefore = scrollEl.scrollHeight;
+ const spacer = document.createElement('div');
+ spacer.style.height = '600px';
+ document.querySelector('.ProseMirror')?.parentElement?.append(spacer);
+ await new Promise((r) => setTimeout(r, 250));
+ await new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+ return scrollEl.scrollHeight - heightBefore;
+ }, SCROLL_SELECTOR);
+ expect(scrollHeightGrowth).toBeGreaterThanOrEqual(600);
+
+ const after = await scrollAndReadFreeze(page, 300);
+ expect(after.frozen).toBe(true);
+ expect(after.pinErrorPx).toBeLessThan(2);
+ const sameAnimations = await page.evaluate(() => {
+ const saved = (window as unknown as { __okHeaderAnimations: Animation[][] })
+ .__okHeaderAnimations;
+ const cells = Array.from(
+ (
+ document.querySelector(
+ '.ProseMirror .tableWrapper > table > tbody tr',
+ ) as HTMLTableRowElement
+ ).cells,
+ );
+ return cells.every((cell, i) => {
+ const current = cell.getAnimations({ subtree: true });
+ const prior = saved[i] ?? [];
+ return (
+ current.length > 0 &&
+ current.length === prior.length &&
+ current.every((animation) => prior.includes(animation))
+ );
+ });
+ });
+ expect(sameAnimations).toBe(true);
+});
+
test('header row stays pinned on deep scroll and releases past the table', async ({
page,
api,