fix(gui-plugins): drive the spreadsheet frame pipeline with an explicit state machine (#61898)

This commit is contained in:
Luke Parker
2026-11-04 21:25:04 -06:00
committed by GitHub
Unverified
parent b13149d762
commit 16c4b36c39
3 changed files with 696 additions and 109 deletions
@@ -0,0 +1,310 @@
import { describe, expect, test } from "bun:test"
import {
SHEET_FRAME_TIMEOUT_MS,
SHEET_SETTLE_DELAY_MS,
createSheetFrameState,
needsSheetOpen,
sameFrameRequest,
sheetEnd,
sheetFrameNeeded,
sheetMoving,
sheetPainted,
sheetPaintFailed,
transitionSheetFrame,
type SheetFrameEvent,
type SheetFrameState,
type SheetFrameTransition,
type SheetNeeded,
} from "./sheet-frame-machine"
import type { SheetFrame, SheetFrameRequest, SheetViewport } from "./sheet-protocol"
const request = (x: number, y: number, wider?: SheetViewport): SheetFrameRequest => ({
sheet: 0,
x,
y,
width: 800,
height: 600,
ratio: 2,
offset: { x: 0.5, y: 0 },
wider,
})
// The bitmap is never drawn here; the machine only hands it to `close-frame` effects.
const frame = (viewport: SheetViewport, end?: { x: number; y: number }): SheetFrame => ({
bitmap: { width: 1, height: 1, close: () => undefined },
viewport,
grid: undefined,
hyperlinks: [],
frozen: { width: 0, height: 0 },
end,
})
const screen = (x: number, y: number) => ({ x, y, width: 800, height: 600 })
const needed = (x: number, y: number): SheetNeeded => ({ x, y, right: x + 800, bottom: y + 600 })
// Folds the events in order and returns the last transition.
const replay = (events: readonly SheetFrameEvent[], state: SheetFrameState = createSheetFrameState()) =>
events.reduce<SheetFrameTransition>((last, event) => transitionSheetFrame(last.state, event), {
state,
effects: [],
})
const opened: SheetFrameEvent = { type: "sheet.opened", width: 800, height: 600 }
describe("transitionSheetFrame", () => {
test("the first paint with a size opens the sheet once", () => {
const state = createSheetFrameState()
expect(needsSheetOpen(state)).toBe(true)
expect(sheetFrameNeeded(state, request(0, 0), undefined)).toBe(false)
const open = transitionSheetFrame(state, opened)
expect(open).toEqual({
state: { status: "idle", scroll: "settled", issued: 0, painted: undefined },
effects: [{ type: "open-sheet", width: 800, height: 600 }],
})
expect(needsSheetOpen(open.state)).toBe(false)
expect(transitionSheetFrame(open.state, opened).state).toBe(open.state)
})
test("a failed viewport is asked for again at the same coordinates", () => {
const failed = replay([
opened,
{ type: "frame.requested", request: request(0, 0) },
{ type: "frame.failed", attempt: 1 },
])
expect(failed.state).toEqual({ status: "failed", scroll: "settled", issued: 1, painted: undefined })
expect(sheetPaintFailed(failed.state)).toBe(true)
// The settle timer, a click or a focus paints again at the same viewport.
expect(sheetFrameNeeded(failed.state, request(0, 0), undefined)).toBe(true)
const retry = transitionSheetFrame(failed.state, { type: "frame.requested", request: request(0, 0) })
expect(retry.effects).toEqual([
{ type: "request-frame", attempt: 2, request: request(0, 0), timeoutMs: SHEET_FRAME_TIMEOUT_MS },
])
// The notice stays up while the retry renders, as it did before.
expect(sheetPaintFailed(retry.state)).toBe(true)
const shown = transitionSheetFrame(retry.state, {
type: "frame.succeeded",
attempt: 2,
request: request(0, 0),
frame: frame(screen(0, 0)),
})
expect(shown.state.status).toBe("idle")
expect(sheetPaintFailed(shown.state)).toBe(false)
})
test("an older frame's failure never shows the notice while a newer one renders or showed", () => {
const pending = replay([
opened,
{ type: "frame.requested", request: request(0, 0) },
{ type: "frame.requested", request: request(0, 300) },
])
for (const event of [
{ type: "frame.failed", attempt: 1 },
{ type: "frame.timed-out", attempt: 1 },
] satisfies SheetFrameEvent[]) {
const older = transitionSheetFrame(pending.state, event)
expect(older.state).toBe(pending.state)
expect(sheetPaintFailed(older.state)).toBe(false)
}
const painted = transitionSheetFrame(pending.state, {
type: "frame.succeeded",
attempt: 2,
request: request(0, 300),
frame: frame(screen(0, 300)),
})
expect(transitionSheetFrame(painted.state, { type: "frame.failed", attempt: 1 }).state).toBe(painted.state)
})
test("a settled scroll asks for the screen alone, however early the timer fired", () => {
const wide = request(0, 300, { x: 0, y: 0, width: 1000, height: 1200 })
const moving = replay([
opened,
{ type: "scroll" },
{ type: "frame.requested", request: wide },
{ type: "frame.succeeded", attempt: 1, request: wide, frame: frame({ x: 0, y: 0, width: 1000, height: 1200 }) },
])
expect(sheetMoving(moving.state)).toBe(true)
// While moving, the wide frame still covers the screen and half the margin.
expect(sheetFrameNeeded(moving.state, request(0, 320), needed(0, 170))).toBe(false)
const settled = transitionSheetFrame(moving.state, { type: "scroll.settled" })
expect(settled.effects).toEqual([{ type: "schedule-paint" }])
expect(sheetMoving(settled.state)).toBe(false)
expect(sheetFrameNeeded(settled.state, request(0, 300), needed(0, 150))).toBe(true)
})
test("scroll events while moving keep the state object and allocate no effects", () => {
const first = replay([opened, { type: "scroll" }])
expect(first.effects).toEqual([
{ type: "restart-settle", delayMs: SHEET_SETTLE_DELAY_MS },
{ type: "schedule-paint" },
])
const second = transitionSheetFrame(first.state, { type: "scroll" })
expect(second.state).toBe(first.state)
expect(second.effects).toBe(first.effects)
const settled = replay([{ type: "scroll.settled" }], replay([opened]).state)
expect(settled.effects).toEqual([])
})
test("an older frame that finishes while a newer one renders shows meanwhile; a later stale one never does", () => {
const pending = replay([
opened,
{ type: "frame.requested", request: request(0, 0) },
{ type: "frame.requested", request: request(0, 100) },
{ type: "frame.requested", request: request(0, 200) },
])
const one = frame(screen(0, 0), { x: 5000, y: 9000 })
const progressive = transitionSheetFrame(pending.state, {
type: "frame.succeeded",
attempt: 1,
request: request(0, 0),
frame: one,
})
expect(progressive.state).toMatchObject({ status: "inflight", attempt: 3 })
expect(sheetPainted(progressive.state)?.attempt).toBe(1)
expect(sheetEnd(progressive.state)).toEqual({ x: 5000, y: 9000 })
expect(progressive.effects).toEqual([{ type: "schedule-paint" }])
const three = frame(screen(0, 200))
const idle = transitionSheetFrame(progressive.state, {
type: "frame.succeeded",
attempt: 3,
request: request(0, 200),
frame: three,
})
expect(idle.state).toMatchObject({ status: "idle", issued: 3 })
expect(idle.effects).toEqual([{ type: "close-frame", frame: one }, { type: "schedule-paint" }])
const two = frame(screen(0, 100))
const late = transitionSheetFrame(idle.state, {
type: "frame.succeeded",
attempt: 2,
request: request(0, 100),
frame: two,
})
expect(late.state).toBe(idle.state)
expect(late.effects).toEqual([{ type: "close-frame", frame: two }])
})
test("the frame on screen or on the way is not asked for twice", () => {
const inflight = replay([opened, { type: "frame.requested", request: request(0, 0) }])
expect(sheetFrameNeeded(inflight.state, request(0, 0), undefined)).toBe(false)
expect(sheetFrameNeeded(inflight.state, request(0, 10), undefined)).toBe(true)
const idle = transitionSheetFrame(inflight.state, {
type: "frame.succeeded",
attempt: 1,
request: request(0, 0),
frame: frame(screen(0, 0)),
})
expect(sheetFrameNeeded(idle.state, request(0, 0), undefined)).toBe(false)
expect(sheetFrameNeeded(idle.state, request(0, 0, screen(0, 0)), undefined)).toBe(true)
})
test("while scrolling, the wider frame on the way covers the screen", () => {
const wide = request(0, 300, { x: 0, y: 0, width: 1000, height: 1200 })
const state = replay([opened, { type: "scroll" }, { type: "frame.requested", request: wide }]).state
expect(sheetFrameNeeded(state, request(0, 320, { x: 0, y: 20, width: 1000, height: 1200 }), needed(0, 170))).toBe(
false,
)
expect(sheetFrameNeeded(state, request(0, 900), needed(0, 750))).toBe(true)
})
test("a hung frame times out into the notice and is withdrawn; an older hung frame is withdrawn too", () => {
const pending = replay([opened, { type: "frame.requested", request: request(0, 0) }])
expect(transitionSheetFrame(pending.state, { type: "frame.timed-out", attempt: 1 })).toEqual({
state: { status: "failed", scroll: "settled", issued: 1, painted: undefined },
effects: [{ type: "abort-frame", attempt: 1 }],
})
const newer = transitionSheetFrame(pending.state, { type: "frame.requested", request: request(0, 100) })
const older = transitionSheetFrame(newer.state, { type: "frame.timed-out", attempt: 1 })
expect(older.state).toBe(newer.state)
expect(older.effects).toEqual([{ type: "abort-frame", attempt: 1 }])
})
test("disposal releases the frame on screen and closes any frame that lands after it", () => {
const one = frame(screen(0, 0))
const shown = replay([
opened,
{ type: "frame.requested", request: request(0, 0) },
{ type: "frame.succeeded", attempt: 1, request: request(0, 0), frame: one },
])
const disposed = transitionSheetFrame(shown.state, { type: "disposed" })
expect(disposed).toEqual({
state: { status: "disposed" },
effects: [{ type: "close-frame", frame: one }, { type: "release" }],
})
expect(transitionSheetFrame(createSheetFrameState(), { type: "disposed" }).effects).toEqual([{ type: "release" }])
const late = frame(screen(0, 100))
expect(
transitionSheetFrame(disposed.state, {
type: "frame.succeeded",
attempt: 2,
request: request(0, 100),
frame: late,
}),
).toEqual({ state: disposed.state, effects: [{ type: "close-frame", frame: late }] })
for (const event of [
{ type: "scroll" },
{ type: "frame.failed", attempt: 1 },
{ type: "frame.requested", request: request(0, 0) },
{ type: "disposed" },
] satisfies SheetFrameEvent[]) {
const after = transitionSheetFrame(disposed.state, event)
expect(after.state).toBe(disposed.state)
expect(after.effects).toEqual([])
}
expect(sheetFrameNeeded(disposed.state, request(0, 0), undefined)).toBe(false)
})
})
describe("sameFrameRequest", () => {
test("compares every field, the wider viewport included", () => {
expect(sameFrameRequest(request(0, 0), request(0, 0))).toBe(true)
expect(sameFrameRequest(request(0, 0), request(1, 0))).toBe(false)
expect(sameFrameRequest(request(0, 0, screen(0, 0)), request(0, 0, screen(0, 0)))).toBe(true)
expect(sameFrameRequest(request(0, 0, screen(0, 0)), request(0, 0))).toBe(false)
expect(sameFrameRequest(request(0, 0), { ...request(0, 0), offset: { x: 0.25, y: 0 } })).toBe(false)
})
})
@@ -0,0 +1,286 @@
import type { SheetFrame, SheetFrameRequest, SheetViewport } from "./sheet-protocol"
/** How long after the last scroll a frame of the screen alone replaces the frames with a margin, in milliseconds. */
export const SHEET_SETTLE_DELAY_MS = 150
/**
* How long one frame may take, its wait behind other workbook calls included, before the grid shows its notice. The
* worker runs calls one at a time, and a large copy holds it for seconds.
*/
export const SHEET_FRAME_TIMEOUT_MS = 30_000
/** Whether the sheet scrolled within the last `SHEET_SETTLE_DELAY_MS`, so frames reach past the screen. */
export type SheetScroll = "settled" | "moving"
/** The frame on screen, the attempt that asked for it, and what it asked for. */
export type SheetPainted = { readonly attempt: number; readonly request: SheetFrameRequest; readonly frame: SheetFrame }
/**
* One sheet grid's frames. Each request takes the next attempt number. A newer request does not withdraw a running
* one: its reply still shows while the newer frame renders, as long as nothing newer has shown.
*/
export type SheetFrameState =
/** The pane has no size yet, and the paper shows. */
| { readonly status: "opening"; readonly scroll: SheetScroll }
/** The newest frame asked for is on screen. */
| {
readonly status: "idle"
readonly scroll: SheetScroll
readonly issued: number
readonly painted: SheetPainted | undefined
}
/** `failed` keeps the notice of an earlier failure up until a frame shows. */
| {
readonly status: "inflight"
readonly scroll: SheetScroll
readonly attempt: number
readonly request: SheetFrameRequest
readonly painted: SheetPainted | undefined
readonly failed: boolean
}
/** The newest frame could not be drawn: the last frame stays, with a notice, and the next paint asks again. */
| {
readonly status: "failed"
readonly scroll: SheetScroll
readonly issued: number
readonly painted: SheetPainted | undefined
}
| { readonly status: "disposed" }
export type SheetFrameEvent =
/** The first paint with a size. */
| { readonly type: "sheet.opened"; readonly width: number; readonly height: number }
| { readonly type: "scroll" }
/** The settle timer fired: no scroll for `SHEET_SETTLE_DELAY_MS`. */
| { readonly type: "scroll.settled" }
/** A paint needs a frame the state neither shows nor waits for (see `sheetFrameNeeded`). */
| { readonly type: "frame.requested"; readonly request: SheetFrameRequest }
| {
readonly type: "frame.succeeded"
readonly attempt: number
readonly request: SheetFrameRequest
readonly frame: SheetFrame
}
/** The worker could not draw the frame, or the call rejected, superseded or withdrawn included. */
| { readonly type: "frame.failed"; readonly attempt: number }
| { readonly type: "frame.timed-out"; readonly attempt: number }
| { readonly type: "disposed" }
export type SheetFrameEffect =
/** Sizes the view and scrolls to where the workbook last showed the sheet, or to a link's target. */
| { readonly type: "open-sheet"; readonly width: number; readonly height: number }
/** Arms the settle timer again. */
| { readonly type: "restart-settle"; readonly delayMs: number }
/** Paints in the next animation frame. */
| { readonly type: "schedule-paint" }
| {
readonly type: "request-frame"
readonly attempt: number
readonly request: SheetFrameRequest
readonly timeoutMs: number
}
| { readonly type: "abort-frame"; readonly attempt: number }
/** Frees the bitmap of a frame that left the screen or never reached it. */
| { readonly type: "close-frame"; readonly frame: SheetFrame }
/** Ends the timers and withdraws every frame still running. */
| { readonly type: "release" }
export type SheetFrameTransition = { readonly state: SheetFrameState; readonly effects: readonly SheetFrameEffect[] }
const NONE: readonly SheetFrameEffect[] = []
// Every scroll event emits these; one array keeps the scroll path free of allocations.
const SCROLLED: readonly SheetFrameEffect[] = [
{ type: "restart-settle", delayMs: SHEET_SETTLE_DELAY_MS },
{ type: "schedule-paint" },
]
const REPAINT: readonly SheetFrameEffect[] = [{ type: "schedule-paint" }]
export function createSheetFrameState(): SheetFrameState {
return { status: "opening", scroll: "settled" }
}
export function transitionSheetFrame(state: SheetFrameState, event: SheetFrameEvent): SheetFrameTransition {
if (state.status === "disposed")
return { state, effects: event.type === "frame.succeeded" ? [{ type: "close-frame", frame: event.frame }] : NONE }
if (event.type === "disposed")
return {
state: { status: "disposed" },
effects:
state.status !== "opening" && state.painted
? [{ type: "close-frame", frame: state.painted.frame }, { type: "release" }]
: [{ type: "release" }],
}
if (event.type === "scroll")
return { state: state.scroll === "moving" ? state : { ...state, scroll: "moving" }, effects: SCROLLED }
if (event.type === "scroll.settled")
return state.scroll === "settled"
? { state, effects: NONE }
: { state: { ...state, scroll: "settled" }, effects: REPAINT }
if (state.status === "opening")
return event.type === "sheet.opened"
? {
state: { status: "idle", scroll: state.scroll, issued: 0, painted: undefined },
effects: [{ type: "open-sheet", width: event.width, height: event.height }],
}
: { state, effects: NONE }
if (event.type === "sheet.opened") return { state, effects: NONE }
if (event.type === "frame.requested") {
const attempt = (state.status === "inflight" ? state.attempt : state.issued) + 1
return {
state: {
status: "inflight",
scroll: state.scroll,
attempt,
request: event.request,
painted: state.painted,
failed: state.status === "failed" || (state.status === "inflight" && state.failed),
},
effects: [{ type: "request-frame", attempt, request: event.request, timeoutMs: SHEET_FRAME_TIMEOUT_MS }],
}
}
if (event.type === "frame.succeeded") return succeeded(state, event)
if (event.type === "frame.timed-out") {
const abort: SheetFrameEffect = { type: "abort-frame", attempt: event.attempt }
// An older frame that hangs holds the worker from the newer one: withdraw it too.
if (state.status !== "inflight" || event.attempt !== state.attempt) return { state, effects: [abort] }
return { state: failed(state), effects: [abort] }
}
// An older request's failure never shows the notice while a newer one is on the way or already showed.
if (state.status !== "inflight" || event.attempt !== state.attempt) return { state, effects: NONE }
return { state: failed(state), effects: NONE }
}
/**
* Whether a paint must ask for a frame: not while a frame on screen, or the one on the way, still covers what the
* scroll needs; not again for the frame on screen or on the way; and always after a failure, so the same viewport is
* asked for again. Runs on every paint, so it allocates nothing.
*/
export function sheetFrameNeeded(
state: SheetFrameState,
input: SheetFrameRequest,
needed: SheetNeeded | undefined,
): boolean {
if (state.status === "opening" || state.status === "disposed") return false
if (
state.scroll === "moving" &&
needed &&
((state.painted && serves(state.painted.request, state.painted.frame.viewport, input, needed)) ||
(state.status === "inflight" && state.request.wider && serves(state.request, state.request.wider, input, needed)))
)
return false
if (state.status === "inflight") return !sameFrameRequest(state.request, input)
if (state.status === "idle") return !state.painted || !sameFrameRequest(state.painted.request, input)
return true
}
/** The area a frame must cover while the sheet scrolls: the screen and half its margin. */
export type SheetNeeded = { readonly x: number; readonly y: number; readonly right: number; readonly bottom: number }
/** Whether the first paint with a size still has to open the sheet. */
export function needsSheetOpen(state: SheetFrameState) {
return state.status === "opening"
}
/** Whether the sheet scrolled within the settle delay, so frames reach past the screen. */
export function sheetMoving(state: SheetFrameState) {
return state.status !== "disposed" && state.scroll === "moving"
}
/** The frame on screen; the paper shows until the first one. */
export function sheetPainted(state: SheetFrameState) {
return state.status === "opening" || state.status === "disposed" ? undefined : state.painted
}
/** Where the sheet's last cell ends, past the frozen panes, as the frame on screen reports it. */
export function sheetEnd(state: SheetFrameState) {
return sheetPainted(state)?.frame.end
}
/** Whether the notice that the cells here cannot be drawn shows. */
export function sheetPaintFailed(state: SheetFrameState) {
return state.status === "failed" || (state.status === "inflight" && state.failed)
}
/** Whether two requests ask for the same frame. */
export function sameFrameRequest(left: SheetFrameRequest, right: SheetFrameRequest) {
return (
left.x === right.x &&
left.y === right.y &&
interchangeable(left, right) &&
(left.wider === right.wider ||
(!!left.wider &&
!!right.wider &&
left.wider.x === right.wider.x &&
left.wider.y === right.wider.y &&
left.wider.width === right.wider.width &&
left.wider.height === right.wider.height))
)
}
/** Whether two frames draw the same sheet into the same screen, so one can stand in for the other. */
export function interchangeable(left: SheetFrameRequest, right: SheetFrameRequest) {
return (
left.sheet === right.sheet &&
left.ratio === right.ratio &&
left.width === right.width &&
left.height === right.height &&
left.offset.x === right.offset.x &&
left.offset.y === right.offset.y
)
}
function serves(request: SheetFrameRequest, viewport: SheetViewport, input: SheetFrameRequest, needed: SheetNeeded) {
return (
interchangeable(request, input) &&
viewport.x <= needed.x &&
viewport.y <= needed.y &&
viewport.x + viewport.width >= needed.right &&
viewport.y + viewport.height >= needed.bottom
)
}
function succeeded(
state: Extract<SheetFrameState, { status: "idle" | "inflight" | "failed" }>,
event: Extract<SheetFrameEvent, { type: "frame.succeeded" }>,
): SheetFrameTransition {
// The worker answers in order, so a frame older than the one on screen only arrives after a race; it never replaces it.
if (event.attempt <= (state.painted?.attempt ?? 0))
return { state, effects: [{ type: "close-frame", frame: event.frame }] }
const painted: SheetPainted = { attempt: event.attempt, request: event.request, frame: event.frame }
const effects: readonly SheetFrameEffect[] = state.painted
? [{ type: "close-frame", frame: state.painted.frame }, { type: "schedule-paint" }]
: REPAINT
if (state.status === "inflight" && event.attempt === state.attempt)
return { state: { status: "idle", scroll: state.scroll, issued: state.attempt, painted }, effects }
// An older frame that finished while the newest renders shows meanwhile, and clears the notice.
if (state.status === "inflight") return { state: { ...state, painted, failed: false }, effects }
return { state: { ...state, painted }, effects }
}
function failed(state: Extract<SheetFrameState, { status: "inflight" }>): SheetFrameState {
return { status: "failed", scroll: state.scroll, issued: state.attempt, painted: state.painted }
}
@@ -1,4 +1,4 @@
import { createMemo, createSignal, createUniqueId, For, onCleanup, Show } from "solid-js"
import { createMemo, createSignal, createUniqueId, For, onCleanup, Show, untrack } from "solid-js"
import { createStore } from "solid-js/store"
import { createResizeObserver } from "@solid-primitives/resize-observer"
import { Loader } from "@opencode/ui/loader"
@@ -33,11 +33,22 @@ import {
rowHeaderWidth,
shiftGrid,
trackIndex,
type Painted,
} from "./sheet-paint"
import type { SheetFrameRequest, SheetLayout, SheetMethods, SheetTab, SheetViewport } from "./sheet-protocol"
import {
createSheetFrameState,
needsSheetOpen,
sheetEnd,
sheetFrameNeeded,
sheetMoving,
sheetPainted,
sheetPaintFailed,
transitionSheetFrame,
type SheetFrameEffect,
type SheetFrameEvent,
} from "./sheet-frame-machine"
import type { SheetFrameRequest, SheetLayout, SheetMethods, SheetTab } from "./sheet-protocol"
import { createOfficeWorker, type WorkerClient } from "./office-worker"
import { SupersededError, WorkerClosedError } from "./worker-rpc"
import { WorkerClosedError } from "./worker-rpc"
/** The workbook worker's end in the window. */
type Client = WorkerClient<SheetMethods>
@@ -48,11 +59,11 @@ type Opened = { readonly client: Client; readonly tabs: readonly SheetTab[]; rea
/** The sheet on show, and the cell a link asked for when one opened it. */
type Shown = { readonly layout: SheetLayout; readonly target: CellAddr | undefined }
/**
* The frames a grid asked the worker for: the newest request's key, how many were sent and the order of the newest that
* arrived, so a late reply never replaces a newer one, and the newest request while its reply is on the way.
*/
type FrameOrder = { requested: string; sent: number; received: number; pending: SheetFrameRequest | undefined }
/** One frame call the worker has not answered yet, and its timeout. */
type FrameCall = { readonly controller: AbortController; readonly timer: number }
/** The timer that ends a scroll once no scroll event came for the settle delay. */
type FrameTimers = { settle: number }
/** The newest sheet pick's request: a newer pick withdraws it, whether it waits for the worker or runs there. */
type Picking = { controller: AbortController | undefined }
@@ -66,9 +77,6 @@ const copyLimit = 200_000
*/
const readerBlock = { rows: 10, cols: 5 }
/** How long after the last scroll a frame of the screen alone replaces the frames with a margin, in milliseconds. */
const settleDelay = 150
/** A read-only Excel workbook with a tab per visible sheet. */
export default function OfficeSpreadsheet(props: FileViewerProps) {
const ctx = usePlugin()
@@ -255,24 +263,21 @@ function SpreadsheetGrid(props: {
let scroller: HTMLDivElement | undefined
let canvas: HTMLCanvasElement | undefined
let frame = 0
// The newest frame from the worker, which stays on screen, following the scroll, until the next one arrives.
let painted: Painted | undefined
// That frame's grid and links where the screen shows them, which pointer hits and links read.
// The frame on screen's grid and links where the screen shows them, which pointer hits and links read.
let shown: { grid: GridMeta | undefined; links: DisplayList } | undefined
// The frames asked for, so a late reply never replaces a newer one.
const frames: FrameOrder = { requested: "", sent: 0, received: 0, pending: undefined }
// When the sheet last scrolled, and the timer that paints once it settles.
const scrolling = { at: -Infinity, timer: 0 }
// Whether the sheet still has to scroll to where the workbook last showed it, or to a link's target.
let opening = true
// What a pointer that is down drags across, and the cell it went down on, which a click without a drag follows.
let drag: "cells" | "rows" | "columns" | undefined
let pressed: CellAddr | undefined
// The frames the worker draws, which the newest reply on screen stays until the next replaces it.
const [frameState, setFrameState] = createSignal(createSheetFrameState())
// The frame calls still running, and the timer that ends scrolling.
const calls = new Map<number, FrameCall>()
const timers: FrameTimers = { settle: 0 }
// Built once: the scroll path dispatches them on every event.
const scrollEvent: SheetFrameEvent = { type: "scroll" }
const settledEvent: SheetFrameEvent = { type: "scroll.settled" }
onCleanup(() => {
controller.abort()
painted?.frame.bitmap.close()
})
onCleanup(() => controller.abort())
// The last paint, in the engine's scroll coordinates: the scroll position, the size of the cells beside the headers,
// the frozen panes', the row headers' width, and the farthest point a jump asked for.
@@ -288,21 +293,20 @@ function SpreadsheetGrid(props: {
reachY: 0,
})
// Where the sheet's last cell ends, past the frozen panes, as the latest frame reports it. A viewport past it makes
// the engine throw.
const [end, setEnd] = createSignal<{ readonly x: number; readonly y: number } | undefined>(undefined, {
// Where the sheet's last cell ends, past the frozen panes, as the frame on screen reports it. A viewport past it
// makes the engine throw.
const end = createMemo(() => sheetEnd(frameState()), undefined, {
equals: (previous, next) => previous?.x === next?.x && previous?.y === next?.y,
})
// `failed` is set while the cells under the scroll position cannot be drawn and the last frame stays on screen.
const paintFailed = createMemo(() => sheetPaintFailed(frameState()))
const [state, setState] = createStore<{
selection: Selection
hover: { cursor: string; title: string | undefined }
failed: boolean
}>({
selection: selectionAt({ row: 0, col: 0 }),
hover: { cursor: "default", title: undefined },
failed: false,
})
const [ratio, setRatio] = createSignal(window.devicePixelRatio || 1)
@@ -353,11 +357,7 @@ function SpreadsheetGrid(props: {
if (size.width <= 0 || size.height <= 0) return
if (opening) {
opening = false
setView({ width: size.width, height: size.height })
open()
}
if (needsSheetOpen(untrack(frameState))) dispatch({ type: "sheet.opened", width: size.width, height: size.height })
const limit = end()
const left = clamp(scroller.scrollLeft, limit ? limit.x + view.frozenWidth - size.width : Infinity)
@@ -366,7 +366,7 @@ function SpreadsheetGrid(props: {
// While the sheet scrolls, frames reach past the screen, so the next scroll still shows cells while its own frame
// renders. Once it settles, a frame of the screen alone replaces it.
const margin = { x: Math.round(size.width / 4), y: Math.round(size.height / 2) }
const moving = performance.now() - scrolling.at < settleDelay
const moving = sheetMoving(untrack(frameState))
const x = Math.max(0, left - margin.x)
const y = Math.max(0, top - margin.y)
@@ -397,25 +397,10 @@ function SpreadsheetGrid(props: {
bottom: Math.min(top + size.height + margin.y / 2, limit.y + view.frozenHeight),
}
const serves = (frame: { readonly request: SheetFrameRequest; readonly viewport: SheetViewport } | undefined) =>
!!frame &&
!!needed &&
interchangeable(frame.request, input) &&
frame.viewport.x <= needed.x &&
frame.viewport.y <= needed.y &&
frame.viewport.x + frame.viewport.width >= needed.right &&
frame.viewport.y + frame.viewport.height >= needed.bottom
// Only the newest request waits its turn in the worker: a scroll that outruns it skips the frames in between.
if (sheetFrameNeeded(untrack(frameState), input, needed)) dispatch({ type: "frame.requested", request: input })
const pending = frames.pending
if (
!moving ||
!(
serves(painted && { request: painted.request, viewport: painted.frame.viewport }) ||
serves(pending?.wider && { request: pending, viewport: pending.wider })
)
)
request(input)
const painted = sheetPainted(untrack(frameState))
// Until the first frame arrives the paper shows.
if (!painted) return setView({ left, top, ...size })
@@ -471,59 +456,78 @@ function SpreadsheetGrid(props: {
if (header !== headers.width) schedule()
}
// Asks the worker for the frame under the scroll position. Only the newest request waits its turn: a scroll that
// outruns the worker skips the frames in between.
const request = (input: SheetFrameRequest) => {
const key = JSON.stringify(input)
const dispatch = (event: SheetFrameEvent) => {
const next = transitionSheetFrame(untrack(frameState), event)
if (key === frames.requested) return
setFrameState(() => next.state)
next.effects.forEach(run)
}
frames.requested = key
frames.pending = input
const run = (effect: SheetFrameEffect) => {
if (effect.type === "schedule-paint") return schedule()
const order = ++frames.sent
if (effect.type === "restart-settle") {
clearTimeout(timers.settle)
timers.settle = window.setTimeout(() => dispatch(settledEvent), effect.delayMs)
const settled = () => {
if (order === frames.sent) frames.pending = undefined
return
}
void props.client.call("frame", input, { key: "frame", signal: controller.signal }).then(
if (effect.type === "request-frame") return requestFrame(effect.attempt, effect.request, effect.timeoutMs)
if (effect.type === "abort-frame") return calls.get(effect.attempt)?.controller.abort()
if (effect.type === "close-frame") return effect.frame.bitmap.close()
if (effect.type === "open-sheet") {
setView({ width: effect.width, height: effect.height })
open()
return
}
clearTimeout(timers.settle)
cancelAnimationFrame(frame)
calls.forEach((call) => {
clearTimeout(call.timer)
call.controller.abort()
})
calls.clear()
}
// Asks the worker for the frame under the scroll position. A newer request with the same key replaces one that
// still waits there; one that runs finishes, and shows while the newer renders.
const requestFrame = (attempt: number, request: SheetFrameRequest, timeoutMs: number) => {
const call: FrameCall = {
controller: new AbortController(),
timer: window.setTimeout(() => dispatch({ type: "frame.timed-out", attempt }), timeoutMs),
}
const settle = () => {
clearTimeout(call.timer)
calls.delete(attempt)
}
calls.set(attempt, call)
void props.client.call("frame", request, { key: "frame", signal: call.controller.signal }).then(
(reply) => {
settled()
if (order < frames.received) return reply?.bitmap.close()
frames.received = order
// Cells the engine cannot draw here leave the last frame on screen, with a notice; the next scroll or resize
// may draw again.
setState("failed", !reply)
if (!reply) return
painted?.frame.bitmap.close()
painted = { request: input, frame: reply }
setEnd(reply.end)
schedule()
settle()
// Cells the engine cannot draw here leave the last frame on screen, with a notice.
dispatch(
reply ? { type: "frame.succeeded", attempt, request, frame: reply } : { type: "frame.failed", attempt },
)
},
(error: Error) => {
settled()
if (error instanceof SupersededError || controller.signal.aborted) return
setState("failed", true)
() => {
settle()
dispatch({ type: "frame.failed", attempt })
},
)
}
// A scroll draws frames with a margin until it settles, when one more paint draws the screen alone.
const scrolled = () => {
scrolling.at = performance.now()
clearTimeout(scrolling.timer)
scrolling.timer = window.setTimeout(schedule, settleDelay)
schedule()
}
onCleanup(() => dispatch({ type: "disposed" }))
onCleanup(() => clearTimeout(scrolling.timer))
// A scroll draws frames with a margin until it settles, when one more paint draws the screen alone.
const scrolled = () => dispatch(scrollEvent)
// One paint per frame, however many scroll, resize and pointer events arrive in it.
const schedule = () => {
@@ -535,7 +539,6 @@ function SpreadsheetGrid(props: {
})
}
onCleanup(() => cancelAnimationFrame(frame))
createResizeObserver(() => scroller, schedule)
// Syncs with the display's pixel ratio, which changes at the same CSS size when the window moves to another screen. A
@@ -1051,7 +1054,7 @@ function SpreadsheetGrid(props: {
</div>
{/* The canvas would cover the scroller's own outline, so the focus ring is laid over both. */}
<div class="pointer-events-none absolute inset-0 peer-focus-visible:shadow-[inset_0_0_0_2px_var(--v2-border-border-focus)]" />
<Show when={state.failed}>
<Show when={paintFailed()}>
<div
role="status"
class="pointer-events-none absolute bottom-3 left-1/2 -translate-x-1/2 rounded-md bg-v2-background-bg-base px-3 py-1.5 text-12-regular text-v2-text-text-muted shadow-[var(--v2-elevation-raised)]"
@@ -1088,18 +1091,6 @@ function place(start: number, size: number, current: number, visible: number, al
return current
}
/** Whether two frames draw the same sheet into the same screen, so one can stand in for the other. */
function interchangeable(left: SheetFrameRequest, right: SheetFrameRequest) {
return (
left.sheet === right.sheet &&
left.ratio === right.ratio &&
left.width === right.width &&
left.height === right.height &&
left.offset.x === right.offset.x &&
left.offset.y === right.offset.y
)
}
function clamp(value: number, max: number) {
return Math.max(0, Math.min(value, max))
}