David/WFDASH-WEBAPP
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
WFDASH-WEBAPP/docs/superpowers/specs/2026-07-07-collection-pool-cluster-sort-design.md
SJCoetz 5f1838051f feat(collection-pool): add nearby supplier cluster sort mode 
Add optional nearby-supplier cluster sort mode to the collection pool table, keeping operational sort as the default. Also includes:
- Update UserSearch component to support fallback selected label for pre-selected values
- Refactor AssignDriverDialog into a separate inner component with intent and pre-filled driver label support
- Add assignment badge helper types and functions
- Add full test coverage for new sort logic and component behaviors
- Update implementation plans and documentation files
- Fix minor code consistency and lint issues across touched files
2026-07-07 21:56:29 +02:00

4 KiB
Raw Blame History

Collection Pool Cluster Sort Design

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

Goal

Add a table sort option to the redesigned collection-pool page so dispatchers can optionally group rows by nearby-supplier cluster while keeping the current operational sort as the default.

User Need

The redesigned collection-pool page already uses side color markers to show nearby suppliers. The next usability improvement is to let operators sort the unified table so suppliers in the same proximity cluster appear together when needed.

Approved Direction

Add a second sort mode for the collection-pool table:

  • default sort: current operational order,
  • alternate sort: nearby-supplier cluster order.

This should sort by the underlying proximity cluster, not by the literal color label text.

Scope

In scope:

  • add a small sort control near the collection-pool filters,
  • preserve the current operational sort as the default,
  • add a Nearby suppliers sort mode,
  • sort rows by cluster membership when the new mode is active,
  • preserve all existing row actions and filters.

Out of scope:

  • adding a true distance-by-distance route optimizer,
  • restoring the old group-by-proximity UI,
  • changing the 2km proximity threshold,
  • changing assignment or ready-state workflows.

Sorting Model

The table should support these sort modes:

  1. Operational
  2. Nearby suppliers

Operational

This remains the current default:

  • assigned today,
  • unassigned,
  • assigned future,
  • then older pool items first,
  • then stable fallback fields.

Nearby Suppliers

When selected, rows should sort by proximity cluster first, then preserve the existing operational order inside each cluster.

Recommended precedence:

  1. cluster group key,
  2. existing operational sort,
  3. stable fallback fields.

This keeps same-cluster suppliers together without losing the dispatcher-friendly ordering inside each nearby group.

Cluster Key

Use the same underlying proximity logic that already powers the side color markers:

  • supplier coordinates from mapped suppliers,
  • clustering within 2km,
  • one passive cluster token shared by nearby suppliers.

The table sort should use that cluster token or a directly related stable cluster key. The user-facing color is only a visual cue; the actual sort should be based on stable cluster membership.

UX Guidance

The control should be small and low-noise, matching the collection-pool redesign.

Recommended UI:

  • label: Sort
  • options: Operational, Nearby suppliers

The control should live near search and ready-state filters without visually dominating them.

Behavior Rules

  • Operational is the default page load state.
  • Search continues to filter before sorting.
  • Ready only and Awaiting only filters continue to work exactly as they do now.
  • Nearby suppliers must not create section headers, subgroups, or nested containers.
  • The table remains one unified list in both sort modes.

Implementation Shape

Expected changes:

  • extend the collection-pool view-model helper to support a selectable sort mode,
  • derive a stable cluster sort key from the same proximity marker pipeline already in use,
  • add a lightweight sort-mode state in page.tsx,
  • add a compact sort control to the filter bar,
  • keep row rendering unchanged apart from the reordered list.

Validation

After implementation, validate that:

  1. the page still defaults to Operational,
  2. switching to Nearby suppliers visibly groups same-cluster suppliers together,
  3. the list remains a single unified stream,
  4. search and ready filters still work in both sort modes,
  5. row actions still behave normally after sorting changes.

Acceptance Criteria

This enhancement is complete when:

  • the collection-pool page offers Operational and Nearby suppliers sort modes,
  • Operational remains the default,
  • Nearby suppliers orders rows by proximity cluster,
  • same-cluster suppliers appear together in the table,
  • no old grouped-by-proximity UI returns,
  • filters and actions continue to work as before.