## 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 leaf owns the Pragmatic DnD primitive for its own DOM surface; 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`).

Begin of the deletion Primitive ownership per topology:

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

## Begin of the insertionKeyEnd of the insertion Begin of the deletion ImportantEnd of the deletion Pragmatic DnD constraint

A Begin of the deletion Pragmatic DnDEnd of the deletion drop target is keyed by its DOM Begin of the insertion`element`: registeringEnd of the insertion Begin of the deletion `element`. RegisteringEnd of the deletion two Begin of the insertion`dropTargetForElements`End of the insertion Begin of the deletion element drop targetsEnd of the deletion on the same Begin of the deletion DOMEnd of the deletion element is Begin of the insertionunsupported (theEnd of the insertion Begin of the deletion not a supported composition model: theEnd of the deletion adapter Begin of the insertionwarns,End of the insertion Begin of the deletion warns that the drop target is already registeredEnd of the deletion and its registry stores one entry per Begin of the insertionelement). SoEnd of the insertion Begin of the deletion element.

That means the earlier shorthand “Sprint / Bucket = `--item --list` on the same element” is not valid when both controllers register `dropTargetForElements`.

## Resolved model

No recursion of controllers (Stimulus targets cannot be assigned toEnd of the deletion a Begin of the deletion specific instance except by DOM ancestry). Instead: a **single root per page** = the whole interaction surface; every draggable/droppable surface carries a **type**; aEnd of the deletion domain object can be **both a list and an item**, but Begin of the insertionthatEnd of the insertion Begin of the deletion a DOM element must have **at most one Pragmatic DnD drop target**.

That “both list and item” model remains composition, butEnd of the deletion composition Begin of the insertionmust beEnd of the insertion Begin of the deletion isEnd of the deletion expressed through Begin of the insertion**distinctEnd of the insertion Begin of the deletion distinctEnd of the deletion DOM Begin of the insertionsurfaces**,End of the insertion Begin of the deletion surfaces,End of the deletion not two drop targets on one element. Begin of the insertionThe shorthand "SprintEnd of the insertion Begin of the deletion Default shape:

| Domain conceptEnd of the deletion / Begin of the deletion surface | controller role |
|---|---|
| Work-package card | `--item` |
| Sprint /End of the deletion Bucket Begin of the insertion= `--item --list` on the same element" is therefore invalid.End of the insertion Begin of the deletion reorder surface | `--item` |
| Sprint / Bucket contained-work-packages surface | `--list` |
| Section (sprints, backlog) | `--list` |End of the deletion

Begin of the insertionDefault dual-roleEnd of the insertion Begin of the deletion ExampleEnd of the deletion shape Begin of the insertion(e.g.End of the insertion Begin of the deletion forEnd of the deletion a future Begin of the insertionSprintEnd of the insertion Begin of the deletion Sprint/BucketEnd of the deletion that is Begin of the deletion bothEnd of the deletion reorderable Begin of the insertion*and*End of the insertion Begin of the deletion andEnd of the deletion accepts Begin of the insertioncards):End of the insertion Begin of the deletion Work package cards:End of the deletion

```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>
```

Begin of the deletion 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:

- a 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.

End of the deletion ## Begin of the deletion Re-evaluation of options

- **C rejected**: cannot express per-element opt-in to draggable/droppable without becoming a type-dispatch matrix that grows with selection + batch + container drag.
- **A viable but weaker**: it can be made to work for current parity, but per-list config and future dual-role surfaces push it toward manual DOM bookkeeping. It does not provide the child registry needed for root-owned selection and broadcast state.
- **B recommended, with a constraint**: leaf controllers compose and localize per-surface config as typed values, and the root gets the child registry it needs. The constraint is that “both list and item” means distinct DOM surfaces or a deliberate composite, never two independent `dropTargetForElements` registrations on the same element.

##End of the deletion Recommendation (not a final decision)

Adopt **B** Begin of the insertion— singleEnd of the insertion Begin of the deletion (singleEnd of the deletion root Begin of the insertioncoordinatorEnd of the insertion + first-class `list`/`item` leaf controllers via Begin of the insertionoutlets — with these constraints:End of the insertion Begin of the deletion outlets), plus:End of the deletion

- Begin of the insertion**One Pragmatic DnD drop target per DOM element.** RepresentEnd of the insertion Begin of the deletion enforce a **single-drop-target-per-DOM-element invariant**;
- representEnd of the deletion dual-role Begin of the deletion BacklogsEnd of the deletion concepts Begin of the insertion(Sprint, Bucket) asEnd of the insertion Begin of the deletion withEnd of the deletion separate Begin of the insertionnested/sibling item + listEnd of the insertion Begin of the deletion item/list DOMEnd of the deletion surfaces by default; Begin of the insertiona deliberate composite controller stays possible if one physical surface must do both.End of the insertion
- Begin of the insertion**MoveEnd of the insertion Begin of the deletion moveEnd of the deletion `acceptedType` to leaf Begin of the insertiontargets**End of the insertion Begin of the deletion targetsEnd of the deletion as Begin of the insertionmulti-valued, per-target config (a card edge accepts `work_package`;End of the insertion a Begin of the insertionSprint list surface accepts `work_package`; a Sprint item surface accepts `sprint`; a bucket item surface accepts `backlog_bucket`).End of the insertion Begin of the deletion multi-valued accepted-types config;End of the deletion
- Begin of the insertion**KeepEnd of the insertion Begin of the deletion keepEnd of the deletion the root as Begin of the insertioncoordinator**End of the insertion Begin of the deletion coordinatorEnd of the deletion for shared state, selection, Begin of the insertiontheEnd of the insertion monitor, move orchestration, and `type → moveUrlTemplate` resolution.

Begin of the insertionWhy B over A/C: theEnd of the insertion Begin of the deletion Rationale:End of the deletion upcoming requirements Begin of the deletion stillEnd of the deletion push toward first-class leaves Begin of the insertion(per-surface typed config) plusEnd of the insertion Begin of the deletion +End of the deletion a coordinator that can enumerate its Begin of the insertionchildren for root-owned selection and broadcast — which A's DOM-walk + root-wide scalar can't give cleanly, and C collapses into a type-dispatch matrix that grows with selection/batch/container drag.End of the insertion Begin of the deletion children. The revisedEnd of the deletion B Begin of the deletion shapeEnd of the deletion keeps those benefits while respecting Begin of the insertiontheEnd of the insertion Begin of the deletion Pragmatic DnD’sEnd of the deletion element-keyed drop-target registry.

## Open questions

- Exact markup shape for #AGILE-175: nested item/list surfaces, sibling surfaces, or a purpose-built composite controller.
- 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.