Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdindex 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.tsindex 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.tsindex 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.tsindex 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,