WFDASH-WEBAPP/docs/superpowers/specs/2026-07-07-collection-pool-redesign-design.md

Collection Pool Redesign Design

Date: 2026-07-07 Area: src/app/(app)/collection-pool/page.tsx Status: Drafted for review

Goal

Redesign the existing collection pool order view so dispatchers work from one simplified operational list instead of the current multi-layered grouped layout. The new view must reduce visual complexity while preserving the current workflow for readiness toggling and driver assignment.

User Problem

The current collection pool page mixes several mental models at once:

• assigned items are split into a separate section,
• unassigned items are grouped by supplier,
• proximity grouping adds cluster headers, controls, and hidden isolated groups,
• bulk controls and nested grouping chrome compete with the row-level actions.

This makes the page harder to scan quickly during dispatch work, especially when the operator needs one answer: what still needs collection, what is already assigned, and what action should happen next.

Approved Direction

Use a single unified operational list with one order_item per row.

This is the chosen direction because it:

• preserves the current per-item workflow,
• keeps all required details visible without opening subpanels,
• removes the split between assigned and unassigned views,
• retains spatial context through lightweight visual tagging instead of grouped sections.

Scope

In scope:

• redesign the Collection Pool page UI and derived view logic,
• flatten assigned and unassigned rows into one list,
• retain Mark Awaiting and Mark Ready row actions,
• show required operational fields on every row,
• replace visible driver names with assignment-status indicators,
• replace the current proximity grouping UI with subtle side color markers,
• preserve Ready only and Awaiting only filtering,
• validate the redesigned page in the browser after implementation.

Out of scope:

• changing PocketBase schema,
• changing assignment API contracts,
• changing driver-app workflows,
• redesigning collection-map,
• introducing a new bulk-action workflow.

Row Model

Each row continues to represent exactly one order_item.

This keeps all current actions aligned to the existing backend write paths and avoids changing operational semantics. The redesign is a view refactor, not a workflow rewrite.

Unified List Structure

The page should derive one visibleRows collection from the loaded order_items.

The unified list includes:

• items in item_status = "collection_pool",
• items in item_status = "assigned",
• rows with a truthy drv_id that still belong in the dispatcher's view until collected.

Assigned rows remain visible in the same list as unassigned rows. They are differentiated only through assignment-state visuals and their row action label.

The current separate assigned section, per-driver subgrouping, per-supplier buckets, visible cluster headers, and isolated footer are removed.

Sorting

The unified list should sort by operational usefulness rather than by nested grouping.

Recommended sort precedence:

1. Assigned for today
2. Unassigned
3. Assigned for a future date
4. Within each bucket above, older pool items first
5. Stable fallback by supplier name, then PO number, then description

Rationale:

• assigned-today items stay visible near the top for same-day operational monitoring,
• unassigned items remain easy to find for active dispatching,
• future assignments stay visible but do not crowd today's work,
• stale items remain easy to escalate.

Required Row Content

Every visible row must show all of the following without expansion:

• supplier name,
• items scheduled for collection,
• associated customer information,
• parent company details,
• time on list expressed in hours or days,
• PO number.

Additional supporting details may remain visible if they do not reintroduce clutter, but the required fields above cannot be hidden behind expansion or secondary panels.

Assignment Status Indicator

Visible driver names are removed from the row UI.

Replace them with a compact assignment-state badge:

• Unassigned
• Assigned today
• Assigned future

Badge meaning:

• Unassigned: no active assignment date for the row,
• Assigned today: assigned and scheduled for the current day,
• Assigned future: assigned with a scheduled date after today.

The assignment badge is the only primary differentiator between assigned and unassigned rows in the unified list.

Ready State

Keep the existing ready workflow and labels:

• Mark Ready
• Mark Awaiting

The ready state remains visible on every row as a small status indicator and is still directly actionable from the row.

Row Actions

The right side of each row contains the operational actions.

Action rules:

• unassigned rows show Assign Driver,
• assigned rows show Reschedule,
• all rows retain the appropriate Mark Ready or Mark Awaiting action.

No separate assigned-only release section should remain in the redesigned layout. If any legacy release-to-pool logic is still required technically, it should not be a dominant layout element and should not recreate the previous split-page structure.

Proximity Context

Remove the current Group by proximity control, cluster headers, radius chips, and isolated footer.

Replace them with subtle side color markers:

• suppliers within roughly 1-2km of one another receive the same side marker color,
• the marker is passive context only,
• the marker should not create new grouping containers, headers, or toggles.

Implementation intent:

• retain useful route-planning context,
• eliminate the visual and interaction overhead of explicit cluster grouping,
• keep the list visually flat.

Filters

Preserve the existing readiness filters exactly:

• Ready only
• Awaiting only

These continue to filter the unified list without changing row structure.

The general search field also remains, since it already supports supplier, description, PO number, and order number lookup.

Layout Guidance

The redesigned list should read as an operational table-like list rather than nested cards within grouped sections.

Design goals:

• consistent column rhythm,
• easy left-to-right scanning,
• minimal vertical chrome,
• clear action target placement,
• assigned and unassigned rows readable in one stream.

Recommended layout pattern:

• thin left color rail for proximity context,
• central content area with stable field placement,
• compact badges for ready state and assignment state,
• right-aligned action button group.

Implementation Approach

Refactor src/app/(app)/collection-pool/page.tsx toward a flatter data and rendering pipeline.

Expected changes:

• replace the current assignedRows, unassignedRows, assignedByDriver, grouped, and renderGroups view model with a single derived list,
• replace explicit cluster rendering with a lightweight proximity-color mapping helper,
• simplify PoolRow so it renders one consistent row shape for all states,
• keep the existing assign dialog and existing PATCH write paths for assignment and ready-state changes,
• remove UI elements that exist only to support the old grouped structure.

Error Handling

Existing error handling behavior should stay intact:

• failed row updates still surface toast errors,
• failed loads still surface a readable load error and empty state fallback,
• missing purchase-order linkage should still be visible on the affected row.

Validation Plan

After implementation, validate in the browser that:

1. the page loads without runtime errors,
2. all collection-pool and assigned items appear in one unified list,
3. assignment badges display correctly for unassigned, today, and future rows,
4. supplier, item, customer, company, age, and PO fields render for every row,
5. Assign Driver appears only on unassigned rows,
6. Reschedule appears only on assigned rows,
7. Mark Ready and Mark Awaiting still work,
8. Ready only and Awaiting only filters still work,
9. proximity side markers render without grouped headers or extra controls,
10. the redesigned layout is visibly flatter and easier to scan than the current page.

Risks And Guardrails

Primary risk:

• flattening the page could accidentally hide useful secondary actions or remove data the operator still depends on.

Guardrails:

• keep all required fields visible,
• keep the existing assignment dialog behavior,
• keep ready-state actions unchanged,
• do not split assigned items into a separate section again,
• do not replace one form of grouping clutter with another.

Acceptance Criteria

The redesign is complete when all of the following are true:

• the collection pool page presents a single unified list,
• assigned items remain visible in that same list,
• driver names are no longer shown,
• assignment state is conveyed by compact visual status,
• required operational details are visible on every row,
• Assign Driver and Reschedule appear contextually,
• Mark Ready and Mark Awaiting still function,
• Ready only and Awaiting only filters are preserved,
• proximity context is reduced to subtle side markers,
• browser validation confirms the simplified layout works end to end.