diff --git a/.changeset/panel-page-ceiling-error.md b/.changeset/panel-page-ceiling-error.md new file mode 100644 index 0000000000..1d29de0d44 --- /dev/null +++ b/.changeset/panel-page-ceiling-error.md @@ -0,0 +1,5 @@ +--- +"@flow-state-dev/react": patch +--- + +`Roster`, `BoardColumns` and `BoardList` now show their error line, with Retry, when a collection still has pages left after 1,000 reads, instead of rendering the rows read so far as the complete list (FIX-1577). diff --git a/packages/react/README.md b/packages/react/README.md index 8e6505f239..d2bb0b96b5 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -535,7 +535,7 @@ It reads through `resourceClient` the same way `Roster` and `BoardColumns` do, a Each panel reads through a resource client. Pass your own through `resourceClient` when your API needs auth headers or a custom `fetch`, and pass a stable reference rather than an object built during render. Left out, each builds its own against the nearest `FlowProvider`'s `baseUrl`, with no auth headers. -`Roster`, `BoardColumns` and `BoardList` read every page of their collection, following the list route's cursor rather than stopping at the first response. `limit` sets the size of each page fetched, not a cap on what renders — a collection larger than `limit` still renders in full. `SeatDetail` reads one item and has no `limit`. +`Roster`, `BoardColumns` and `BoardList` follow the list route's cursor for up to 1,000 pages rather than stopping at the first response. `limit` sets the size of each page fetched, not a cap on what renders. A collection with pages left after 1,000 reads shows the error line and Retry instead of the rows read so far, because those aren't the whole list. Retry stops at the same point. If your `limit` is below 200, the list route's maximum, raising it lets the panel read further, and at `limit={200}` the ceiling is about 200,000 rows. Both hold only when the collection returns the page size you ask for: a projected collection may treat `limit` as a hint and return smaller pages, so raising it may not help there. A collection larger than that isn't one these panels are meant to show. A custom `resourceClient` whose cursor never ends hits the same error at any `limit`, and the fix belongs in that client. `SeatDetail` reads one item and has no `limit`. A failed read shows what failed and offers a retry. Nothing re-reads on a timer. diff --git a/packages/react/src/components/panels/BoardColumns.ts b/packages/react/src/components/panels/BoardColumns.ts index 398227c5d5..797d0492e0 100644 --- a/packages/react/src/components/panels/BoardColumns.ts +++ b/packages/react/src/components/panels/BoardColumns.ts @@ -96,8 +96,10 @@ export type BoardColumnsProps = { */ readonly resourceClient?: PanelRowSource; /** - * Rows to request per page. The panel reads every page regardless — this - * sets the size of each fetch, not a cap on what renders (BR-21). + * Rows to request per page: the size of each fetch, not a cap on what + * renders. The panel follows the cursor for up to 1,000 pages; a collection + * with pages left after that shows the error line and Retry, never the + * rows read so far (BR-21). See `usePanelRows`. */ readonly limit?: number; readonly slots?: BoardColumnsSlots; diff --git a/packages/react/src/components/panels/BoardList.ts b/packages/react/src/components/panels/BoardList.ts index edb1944728..850adc14cc 100644 --- a/packages/react/src/components/panels/BoardList.ts +++ b/packages/react/src/components/panels/BoardList.ts @@ -43,7 +43,12 @@ type BoardListCommonProps = { * segment, so it carries no slash. */ readonly boardRef: string; - /** Rows to request per page. The list reads every page regardless. */ + /** + * Rows to request per page: the size of each fetch, not a cap on what + * renders. The list follows the cursor for up to 1,000 pages; a collection + * with pages left after that shows the error line and Retry, never the + * rows read so far. See `usePanelRows`. + */ readonly limit?: number; readonly slots?: BoardListSlots; }; diff --git a/packages/react/src/components/panels/Roster.ts b/packages/react/src/components/panels/Roster.ts index 888602b940..0da7b5842e 100644 --- a/packages/react/src/components/panels/Roster.ts +++ b/packages/react/src/components/panels/Roster.ts @@ -93,8 +93,10 @@ export type RosterProps = { */ readonly resourceClient?: PanelRowSource; /** - * Seats to request per page. The panel reads every page regardless — this - * sets the size of each fetch, not a cap on what renders (BR-19). + * Seats to request per page: the size of each fetch, not a cap on what + * renders. The panel follows the cursor for up to 1,000 pages; a collection + * with pages left after that shows the error line and Retry, never the + * rows read so far (BR-19). See `usePanelRows`. */ readonly limit?: number; readonly slots?: RosterSlots; diff --git a/packages/react/src/components/panels/reads.ts b/packages/react/src/components/panels/reads.ts index 59d1e115c5..4b0f7b5e7e 100644 --- a/packages/react/src/components/panels/reads.ts +++ b/packages/react/src/components/panels/reads.ts @@ -46,12 +46,15 @@ const EMPTY: PanelRow[] = []; /** * A ceiling on pages read for ONE identity, not on rows. * - * Both panels are "a list a person scans" (see `usePanelRows`), not a feed + * The panels are "a list a person scans" (see `usePanelRows`), not a feed * with an unbounded tail, so this is a guard against a misbehaving transport * handing back a `nextCursor` forever rather than a limit anyone is expected * to reach. At the route's largest page (`STATE_LIST_MAX_LIMIT`, 200 — * `packages/engine/src/routes/resource-routes.ts`) this still covers 200,000 - * rows before it gives up and shows what it has. + * rows, when the collection honours the requested page size (a projected + * collection may treat `limit` as a hint and return smaller pages). Reaching it with a `nextCursor` still outstanding is a read failure, + * not a result: the panel shows its error, never the pages it got as if they + * were the whole list (BR-19, BR-21). */ const MAX_PAGES = 1000; @@ -200,15 +203,16 @@ function liveBoardDriver(sessionId: string, boardRef: string, live: PanelLive): /** * Every row of a collection, for one session — traversing `nextCursor` until - * the route stops returning one. + * the route stops returning one, for up to `MAX_PAGES` (1,000) pages. * - * Deliberately no `loadMore`: both panels draw a standing list that a person + * Deliberately no `loadMore`: the panels draw a standing list that a person * scans, not a feed they page through, and a cursor the host cannot see is * worse than none. `limit` sets the page **size** the read requests each * time, not a cap on what the panel shows — a collection larger than `limit` - * still renders every row, in `limit`-sized fetches (bounded by `MAX_PAGES`, - * see above), because a panel that stopped at the first page would truncate - * silently (BR-19, BR-21). + * is read in `limit`-sized fetches, because a panel that stopped at the first + * page would truncate silently. A collection with pages left after + * `MAX_PAGES` reads is an error (the panel's error line and Retry), never the + * rows read so far. * * With `live`, `ref` is a task board, and the rows are read again whenever * the session keeps a change to it (see `liveBoardDriver`). Without it they @@ -246,10 +250,12 @@ export function usePanelRows( for (const item of page.items) { collected.push({ topic: item.topic, clientData: item.clientData as TClient }); } - if (page.nextCursor === undefined) break; + if (page.nextCursor === undefined) return collected; cursor = page.nextCursor; } - return collected; + throw new Error( + `Stopped after ${MAX_PAGES} pages with more still to read, rather than show part of the list as all of it.` + ); }, driver ); diff --git a/packages/react/test/board-list.test.ts b/packages/react/test/board-list.test.ts index 73ab7a6fa8..4bd8b5b099 100644 --- a/packages/react/test/board-list.test.ts +++ b/packages/react/test/board-list.test.ts @@ -246,6 +246,23 @@ describe("BoardList · the list (V1)", () => { await waitFor(() => expect(rowIds()).toEqual(["t-1"])); }); + it("errors rather than draw a partial list when the board never stops paging", async () => { + // A transport that hands back a `nextCursor` forever, one row per page. + let n = 0; + const endless = { + listCollectionItems: vi.fn(async () => { + const row = card(`t-${n++}`, "pending"); + return { items: [row], nextCursor: row.topic }; + }) + }; + render(createElement(BoardList, { sessionId: SESSION, boardRef: BOARD, resourceClient: endless })); + await waitFor(() => expect(screen.getByRole("alert").textContent).toMatch(/more still to read/)); + expect(screen.getByRole("button", { name: "Retry" })).toBeTruthy(); + expect(rowIds()).toEqual([]); + // Stops at the ceiling rather than reading forever. + expect(endless.listCollectionItems).toHaveBeenCalledTimes(1000); + }); + it("wraps a host's row body in the list's own row, and says what a host's empty slot says", async () => { render( createElement(BoardList, { diff --git a/packages/react/test/panels.test.ts b/packages/react/test/panels.test.ts index 31d1a73440..d6ba7828b0 100644 --- a/packages/react/test/panels.test.ts +++ b/packages/react/test/panels.test.ts @@ -75,6 +75,20 @@ function pagedSource(items: Array<{ topic: string; clientData: unknown }>, pageS return { listCollectionItems }; } +/** + * A transport that never stops handing back a `nextCursor` — one row per page, + * forever. The misbehaving source the panels' page ceiling exists for. + */ +function endlessSource(row: (n: number) => { topic: string; clientData: unknown }) { + let n = 0; + return { + listCollectionItems: vi.fn(async () => { + const item = row(n++); + return { items: [item], nextCursor: item.topic }; + }) + }; +} + const seat = (seatId: string, flow = "agent") => ({ topic: seatId, clientData: { seatId, flow, instructions: null } @@ -212,6 +226,41 @@ describe("Roster", () => { // Two requests: the first page and the one the cursor points to. expect(source.listCollectionItems).toHaveBeenCalledTimes(2); }); + + it("errors rather than render a partial roster when the page ceiling is hit with rows left", async () => { + // `limit={1}` is a valid page size, so 1,001 seats need 1,001 pages — one + // past the ceiling. Rendering the first 1,000 as the roster would drop a + // seat with nothing on screen to say so. + const seats = Array.from({ length: 1001 }, (_, i) => seat(`seat-${String(i).padStart(4, "0")}`)); + const source = pagedSource(seats); + render( + createElement(Roster, { sessionId: "s1", resourceClient: source, collectionRef: "roster", limit: 1 }) + ); + + await waitFor(() => expect(screen.getByRole("alert")).toBeTruthy()); + expect(screen.getByText(/more still to read/)).toBeTruthy(); + expect(screen.getByRole("button", { name: "Retry" })).toBeTruthy(); + expect(screen.queryByText("seat-0000")).toBeNull(); + expect(document.querySelector("[data-roster-seats]")).toBeNull(); + expect(source.listCollectionItems).toHaveBeenCalledTimes(1000); + }); + + it("renders a roster that ends exactly on the last page the ceiling allows", async () => { + // The other side of the boundary: 1,000 pages whose last carries no + // cursor is a complete read, not a truncated one. + const seats = Array.from({ length: 1000 }, (_, i) => seat(`seat-${String(i).padStart(4, "0")}`)); + const source = pagedSource(seats); + render( + createElement(Roster, { sessionId: "s1", resourceClient: source, collectionRef: "roster", limit: 1 }) + ); + + await waitFor(() => expect(screen.getByText("seat-0999")).toBeTruthy()); + expect(screen.queryByRole("alert")).toBeNull(); + expect(document.querySelector("[data-roster-seats]")?.getAttribute("data-roster-seats")).toBe( + "1000" + ); + expect(source.listCollectionItems).toHaveBeenCalledTimes(1000); + }); }); // --------------------------------------------------------------------------- @@ -369,4 +418,15 @@ describe("BoardColumns", () => { expect(text).not.toMatch(/worker-9|expiresAt|boom|write ?log/i); } ); + + it("errors rather than render a partial board when the cursor never runs out", async () => { + const source = endlessSource((n) => card(`t-${n}`, "pending", { title: `task ${n}` })); + render(createElement(BoardColumns, { sessionId: "s1", boardRef: "b", resourceClient: source })); + + await waitFor(() => expect(screen.getByRole("alert")).toBeTruthy()); + expect(screen.getByText(/more still to read/)).toBeTruthy(); + expect(document.querySelectorAll("[data-task-id]").length).toBe(0); + // Stops at the ceiling rather than reading forever. + expect(source.listCollectionItems).toHaveBeenCalledTimes(1000); + }); });