## Context

Migrating Backlogs from dragula to Atlassian Pragmatic DnD (#AGILE-251). Open question: what controller topology should the reusable `sortable-lists` Stimulus primitive take, given upcoming requirements — #AGILE-181 (multi-select + batch move), #AGILE-175 (draggable buckets/sprints), #AGILE-278 (bulk move action), #AGILE-284 (optimistic reordering).

`sortable-lists` lives in generic `frontend/src/stimulus/controllers/dynamic/` — a reusable primitive, not backlogs-specific. Backlogs is its first consumer, so API quality matters beyond Backlogs.

## Options considered

- **A — 2 controllers** (current branch): root `SortableListsController` owns the monitor, per-list drop targets, and the optimistic move/persist/rollback transaction; per-card `ItemController`. A list is a *target* of the root. Item↔root via DOM walk (`closest`) + reading a `data-…-accepted-type` attr.
- **B — 3 controllers via outlets** (experiment PR https://github.com/opf/openproject/pull/23739): adds a first-class `ListController`; the root coordinates `list` + `item` leaves via Stimulus outlets. Each Begin of the insertionleafEnd of the insertion Begin of the deletion listEnd of the deletion owns Begin of the insertionthe Pragmatic DnD primitive forEnd of the insertion its Begin of the insertionown DOM surface;End of the insertion Begin of the deletion drop target + per-list values;End of the deletion the root pushes shared state down and reads its children as a live collection.
- **C — 1 monolith** (the original `generic-drag-and-drop` topology, re-done in Pragmatic): one controller owns everything via targets.

## Topology illustration


Pragmatic DnD primitives: **[M]** Monitor (`monitorForElements` — one per surface, runs the actual drop) · **[D]** Drop Target (`dropTargetForElements`) · **[G]** Draggable (`draggable`).

Primitive ownership per topology:

| Primitive | A (2 ctrl) | B (3 ctrl) | C (monolith) |
|---|---|---|---|
| Monitor | root | root | one controller |
| Drop Target — list | root | **list** | one controller |
| Drop Target — Begin of the insertioncard/itemEnd of the insertion Begin of the deletion cardEnd of the deletion edge | item | item | one controller |
| Draggable — Begin of the insertioncard/itemEnd of the insertion Begin of the deletion cardEnd of the deletion | item | item | one controller |

Begin of the insertion## Important Pragmatic DnD constraint

A Pragmatic DnD drop target is keyed by its DOM `element`. Registering two element drop targets onEnd of the insertion Begin of the deletion Under B,End of the deletion the Begin of the insertionsame DOMEnd of the insertion Begin of the deletion future "both list and item"End of the deletion element Begin of the insertionis notEnd of the insertion Begin of the deletion (a Sprint) simply stacks both controllers — `data-controller="… list … item"` — giving itEnd of the deletion a Begin of the insertionsupported composition model: the adapter warns that the drop target is already registeredEnd of the insertion Begin of the deletion Drop Target (accepts cards)End of the deletion and Begin of the deletion a Draggable (reorderable withinEnd of the deletion its Begin of the insertionregistry stores one entry per element.

That meansEnd of the insertion Begin of the deletion section) with no new machinery. B isEnd of the deletion the Begin of the insertionearlier shorthand “Sprint / Bucket = `--item --list` onEnd of the insertion Begin of the deletion only topology where each primitive is co-located withEnd of the deletion the Begin of the insertionsame element” is not valid when both controllers register `dropTargetForElements`.End of the insertion Begin of the deletion controller that owns it.End of the deletion

## Resolved model

No recursion of controllers (Stimulus targets cannot be assigned to a specific instance except by DOM ancestry). Instead: a **single root per page** = the whole interaction surface; every Begin of the insertiondraggable/droppable surfaceEnd of the insertion Begin of the deletion elementEnd of the deletion carries a **type**; Begin of the insertiona domain objectEnd of the insertion Begin of the deletion an elementEnd of the deletion can be **both a list and an Begin of the insertionitem**, butEnd of the insertion Begin of the deletion item** (a Sprint is draggable as `sprint` andEnd of the deletion a Begin of the insertionDOM element must have **at most one Pragmatic DnDEnd of the insertion drop Begin of the insertiontarget**.End of the insertion Begin of the deletion container accepting `work_package`). Drop acceptance = `accepts(target.acceptedType, dragData.type)`, per-list and multi-valued.End of the deletion

That Begin of the insertion“bothEnd of the insertion Begin of the deletion "bothEnd of the deletion list and Begin of the insertionitem”End of the insertion Begin of the deletion item"End of the deletion model Begin of the insertionremains composition, but compositionEnd of the insertion is Begin of the deletion *composition*,End of the deletion expressed Begin of the insertionthrough distinct DOM surfaces, not two drop targets on one element. Default shape:End of the insertion Begin of the deletion as stacked `data-controller` values:End of the deletion

| Begin of the insertionDomain concept / surfaceEnd of the insertion Begin of the deletion ElementEnd of the deletion | Begin of the insertioncontroller roleEnd of the insertion Begin of the deletion controllersEnd of the deletion |
|---|---|
| Work-package card | `--item` |
| Sprint / Bucket Begin of the insertionreorder surfaceEnd of the insertion | Begin of the insertion`--item`End of the insertion Begin of the deletion `--item --list`End of the deletion |
| Begin of the insertionSprint / Bucket contained-work-packages surface | `--list` |
|End of the insertion Section (sprints, backlog) | `--list` |

Begin of the insertionExample shape for a future Sprint/Bucket that is both reorderable and accepts Work package cards:

```html
<li data-controller="sortable-lists--item" data-sortable-lists--item-type-value="sprint">
<section data-controller="sortable-lists--list" data-sortable-lists--list-type-value="sprint">
... work package cards ...
</section>
</li>
```

A coordinated composite drop-target controller remains possible, but the default recommendation is separate nested or sibling DOM surfaces because it keeps Pragmatic DnD ownership unambiguous.

Drop acceptance should move from a root-wide scalar to per-target, multi-valued configuration:

End of the insertion - Begin of the insertiona Work package card item edge accepts `work_package` when reordering cards;
- a Sprint list surface accepts `work_package` when moving cards into the Sprint;
- a Sprint item surface accepts `sprint` when reordering Sprints;
- a Backlog bucket item surface accepts `backlog_bucket` when reordering buckets.

## Re-evaluation of options

-End of the insertion **C rejected**: cannot express per-element opt-in to Begin of the insertiondraggable/droppable without becomingEnd of the insertion Begin of the deletion draggable/droppable; becomesEnd of the deletion a type-dispatch matrix that grows with selection + batch + container drag.
- **A viable but weaker**: Begin of the insertionit can be made to work for current parity, butEnd of the insertion per-list config Begin of the insertionand future dual-role surfaces push itEnd of the insertion Begin of the deletion (now multi accepted-types) degrades into stringly DOM attributes; "both" is asymmetric (root-target + item-controller). Adequate for parity only; driftsEnd of the deletion toward Begin of the insertionmanual DOM bookkeeping. It does not provideEnd of the insertion Begin of the deletion B asEnd of the deletion the Begin of the insertionchild registry needed for root-owned selection and broadcast state.End of the insertion Begin of the deletion requirements land.End of the deletion
- **B Begin of the insertionrecommended, with a constraint**:End of the insertion Begin of the deletion recommended**:End of the deletion leaf controllers Begin of the insertioncompose andEnd of the insertion Begin of the deletion compose,End of the deletion localize Begin of the insertionper-surfaceEnd of the insertion Begin of the deletion per-elementEnd of the deletion config as typed values, and Begin of the deletion giveEnd of the deletion the root Begin of the insertiongetsEnd of the insertion the Begin of the insertionchild registryEnd of the insertion Begin of the deletion **child registry**End of the deletion it Begin of the insertionneeds. The constraintEnd of the insertion Begin of the deletion needs to broadcast state and drive multi-select. A sync `closest()` lookupEnd of the deletion is Begin of the deletion child→parent only and cannot provideEnd of the deletion that Begin of the insertion“both list and item” means distinct DOM surfaces or a deliberate composite, never two independent `dropTargetForElements` registrations on the same element.End of the insertion Begin of the deletion collection.End of the deletion

## Recommendation (not a final decision)

Adopt **B** (single root + first-class `list`/`item` leaf controllers via outlets), plus: Begin of the insertion

- enforce a **single-drop-target-per-DOM-element invariant**;
- represent dual-role Backlogs concepts with separate item/list DOM surfaces by default;
- moveEnd of the insertion `acceptedType` Begin of the insertionto leaf targets as a multi-valued accepted-types config;
- keepEnd of the insertion Begin of the deletion becomes per-list and multi-valued;End of the deletion the root Begin of the insertionas coordinator for shared state, selection, monitor, move orchestration, andEnd of the insertion Begin of the deletion holds aEnd of the deletion `type → moveUrlTemplate` Begin of the insertionresolution.End of the insertion Begin of the deletion map resolved by dragged type at drop.End of the deletion

Rationale: Begin of the deletion bothEnd of the deletion upcoming requirements Begin of the insertionstillEnd of the insertion push toward first-class leaves + a coordinator that can enumerate its children. Begin of the insertionThe revisedEnd of the insertion B Begin of the insertionshape keeps those benefits while respecting Pragmatic DnD’s element-keyed drop-target registry.End of the insertion Begin of the deletion is the cheapest path that does not require rework when #AGILE-175 / #AGILE-181 land.End of the deletion

## Open questions

- Begin of the insertionExact markup shape for #AGILE-175: nested item/list surfaces, sibling surfaces, or a purpose-built composite controller.
-End of the insertion Ordering rule for the N selected within the target (selection order vs source Position).
- Partial-failure / atomicity of the batch move (#AGILE-278).
- Multi-card drag preview Begin of the insertion(“N cards”)End of the insertion Begin of the deletion ("N cards")End of the deletion behaviour.
- Confirm no turbo-stream re-renders the root *element* itself (would drop the in-memory selection `Set`).
- Whether #AGILE-175 / #AGILE-181 belong in the generic `sortable-lists` primitive or in backlogs-specific adapters.