Skip to content
Merged
Show file tree
Hide file tree
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/panel-page-ceiling-error.md
Original file line number Diff line number Diff line change
@@ -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).
2 changes: 1 addition & 1 deletion packages/react/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. At `limit={200}` the ceiling is about 200,000 rows; 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`.
Comment thread
jhoffner marked this conversation as resolved.
Resolved

A failed read shows what failed and offers a retry. Nothing re-reads on a timer.

Expand Down
6 changes: 4 additions & 2 deletions packages/react/src/components/panels/BoardColumns.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
7 changes: 6 additions & 1 deletion packages/react/src/components/panels/BoardList.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
};
Expand Down
6 changes: 4 additions & 2 deletions packages/react/src/components/panels/Roster.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
23 changes: 14 additions & 9 deletions packages/react/src/components/panels/reads.ts
Original file line number Diff line number Diff line change
Expand Up @@ -46,12 +46,14 @@ const EMPTY: PanelRow<never>[] = [];
/**
* 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. 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;

Expand Down Expand Up @@ -200,15 +202,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
Expand Down Expand Up @@ -246,10 +249,12 @@ export function usePanelRows<TClient = unknown>(
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.`
);
Comment thread
jhoffner marked this conversation as resolved.
Resolved
Comment thread
jhoffner marked this conversation as resolved.
Resolved
},
driver
);
Expand Down
17 changes: 17 additions & 0 deletions packages/react/test/board-list.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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, {
Expand Down
60 changes: 60 additions & 0 deletions packages/react/test/panels.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 }
Expand Down Expand Up @@ -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);
});
});

// ---------------------------------------------------------------------------
Expand Down Expand Up @@ -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);
});
});
Loading