Files

T

Emad Ibrahim afb73ba553 Scale issue kanban board for high-volume columns (#5309 )

## Thinking Path

> - Paperclip is a control plane for autonomous AI-agent companies, and
the board UI needs to keep operator visibility clear as company work
scales.
> - The involved subsystem is the Issues page board mode, specifically
the Kanban rendering path for issue status columns.
> - The current board keeps the classic Kanban model, but high-volume
columns can become tall, slow, and hard to scan when hundreds of issues
are loaded.
> - We explored alternatives and chose the conservative Scaled Kanban
direction: preserve status lanes and drag/drop, but bound visible cards
and collapse low-signal lanes.
> - This pull request adds UI-only density controls and high-volume
defaults rather than introducing schema or API changes.
> - The benefit is a board that remains usable with large issue
inventories while keeping active workflow lanes visible.

## What Changed

- Added scaled Kanban behavior with compact cards, collapsed cold-lane
rails, per-column visible-card limits, and per-column "show more" reveal
controls.
- Added persisted board density preferences to the Issues page view
state, scoped through the existing company-specific localStorage path.
- Added board toolbar controls for compact cards, collapsed cold lanes,
cards-per-column page size (`10`, `25`, `50`), and density reset.
- Added a design spec and implementation plan under `doc/plans/`.
- Added focused Vitest coverage for `KanbanBoard` and `IssuesList`
high-volume board behavior.

## Verification

- `pnpm exec vitest run ui/src/components/IssuesList.test.tsx
ui/src/components/KanbanBoard.test.tsx` — pass, 35 tests.
- `pnpm -r typecheck` — pass.
- `pnpm build` — pass before the upstream merge; not rerun after
docs/assets cleanup.
- `curl -fsS http://127.0.0.1:3100/api/health` — pass against restarted
local dev server after applying pending migration
`0078_white_darwin.sql`.
- `pnpm test:run` — previously failed in unrelated Cursor remote-sandbox
server tests:
- `server/src/__tests__/cursor-local-adapter-environment.test.ts`:
expected probe status `pass`, received `fail`.
- `server/src/__tests__/cursor-local-execute.test.ts`: two remote
sandbox execution cases exited `127` instead of `0`.

Local dev server for manual UI inspection: `http://127.0.0.1:3100`.

Screenshots were captured for review and attached in the PR thread
rather than committed to source.

## Risks

- Low schema/API risk: this is UI-only and uses the existing issue data
path.
- Board users may need to notice the new density controls if they want
to override high-volume defaults.
- Collapsed cold lanes remain valid drop targets, so status moves can
happen without expanding the destination lane.
- Very large remote columns can still hit the existing 200-item
per-column query cap; this PR improves rendering, not server-side board
pagination.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex coding agent based on GPT-5, with repository tool use,
shell execution, local test/build execution, and inline implementation
planning. No subagents were used.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

2026-05-15 10:53:09 -05:00

4.6 KiB

Raw Permalink Blame History

Scaled Kanban Board Design

Date: 2026-05-05 Branch: feat/scaled-kanban-board

Context

The Issues page currently supports list and board modes. List mode already has grouping, sorting, filtering, nested parent/child rows, deferred row rendering, and incremental render limits. Board mode uses classic status columns with draggable cards. It fetches per-status board data, but the current UI still presents each lane as an unbounded stack of cards, which becomes tall and heavy when a company has hundreds of issues.

The goal is to keep the Kanban mental model while making high-volume boards usable. This is a UI-first change. It should not introduce schema changes or new API contracts in the first pass.

Problem

When Paperclip has many issues, board columns get too tall and slow. The operator loses the ability to scan the board quickly, and rendering or dragging through long columns becomes unpleasant. The first version should solve this by reducing the number of visible cards per column and by collapsing low-signal columns, not by replacing Kanban with a different inventory surface.

Design

Board mode remains status-column based. Each column shows its total issue count, a bounded set of visible cards, and a local affordance to reveal more cards in that column. The board should keep active workflow lanes expanded by default and collapse cold or noisy lanes once issue volume is high.

Default high-volume behavior activates when the filtered board has more than 100 issues:

Compact cards are used by default.
backlog, done, and cancelled auto-collapse to narrow rails.
todo, in_progress, in_review, and blocked remain expanded by default.
Each expanded column renders an initial 10 cards by default.
The user can choose a page size of 10, 25, or 50 cards per column.
The user can reveal one additional page at a time in each column without changing other columns.
Drag and drop continues to work for visible cards.

The toolbar should expose compact controls for:

toggling compact cards
hiding or showing cold lanes
choosing cards per column
resetting board density to defaults

These preferences should persist through the existing issue view-state/localStorage mechanism and remain scoped by company.

Component Shape

IssuesList remains the owner of issue board view state. It should store board-density preferences alongside the existing issue view state, including compact card preference, cold-lane mode, and cards-per-column page size.

KanbanBoard receives board tuning props from IssuesList and delegates per-lane display to KanbanColumn.

KanbanColumn owns only local presentation mechanics for a lane:

whether the lane is rendered as an expanded column or collapsed rail
how many cards are currently visible in that lane
the local "show more" action

KanbanCard gets a compact variant. The compact card should still show the issue identifier, title, live state, priority, and assignee when available, but with tighter spacing and fewer vertical affordances.

Data Flow

The first implementation uses the current issue data already available to board mode. No database, shared type, or route change is required.

Column totals are computed from the in-memory filtered board issues. If a column reaches the existing remote board query cap, the existing warning remains the truth source that more filtering may be required.

Future server-side column pagination can be added later if the UI-only version is not enough for very large instances.

Error Handling

This feature should not introduce new network errors. Existing issue loading and update errors continue to surface through the Issues page.

For drag and drop:

Moving a visible card keeps the current optimistic behavior.
Hidden cards remain hidden until revealed.
A collapsed lane rail is a valid drop target. Dropping onto it moves the issue to that status and keeps the lane collapsed.

Testing

Focused tests should cover:

board mode passes density preferences into KanbanBoard
columns render only the initial visible card count
"show more" reveals more cards in a single column
high-volume cold lanes render as collapsed rails by default
compact cards preserve identifier/title/live/priority/assignee signals
drag/drop status updates still call onUpdateIssue

Manual verification should include opening the Issues board with a large fixture or mocked issue set and confirming that columns remain usable with hundreds of issues.

Out of Scope

Server-side per-column pagination
New issue schema fields
Replacing Kanban with a dense table or action-only board
Changing issue status semantics
Broad visual redesign of the Issues page

4.6 KiB Raw Permalink Blame History