Content
View differences
Updated by Alexander Coles 1 day ago
**As** a user of OpenProject's Backlogs module
**I want to** use drag and drop to move items
**so that** can manage my backlogs, buckets and sprints effectively.
---
### Acceptance Criteria (Refined)
#### Scenario 1: Reordering within the same list
* **Given** a user with "manage backlog/sprint items" permissions
* **When** they drag a Work Package card up or down within its current list
* **Then** a visual drop indicator (highlighted gap) appears at valid drop positions.
* **And When** they drop the card
* **Then** the card instantly moves to the new position (optimistic update).
* **And** the new order is persisted to the server.
* **And** refreshing the page confirms the new order.
#### Scenario 2: Moving between lists
* **Given** a user with "manage backlog/sprint items" permissions
* **When** they drag a card from an Inbox backlog
* **And** hover over an empty Sprint list
* **Then** the empty Sprint list visually indicates it can accept the drop.
* **When** they drop the card
* **Then** the card instantly appears in the Sprint list.
* **And** the move is persisted to the server.
#### Scenario 3: Missing Permissions
* **Given** a user **without** "manage backlog/sprint items" permissions
* **When** they attempt to click and drag a Work Package card
* **Then** the card cannot be picked up (no drag state is initiated).
#### Scenario 4: Optimistic Update Failure (Server Error)
* **Given** a user drags and drops a card to a new position
* **When** the server returns an error (e.g., network failure or concurrent edit)
* **Then** the card reverts to its original position.
* **And** an error flash notice is displayed explaining the failure.
#### Scenario 5: Card Visibility After Move
* **Given** a user's current view filters out closed items
* **When** they drag a card into a Sprint where a workflow rule automatically closes it
* **Then** the card disappears from the view.
* **And** a notification/toast is shown informing the user that the moved item is no longer visible in the current view.
#### Scenario 6: Auto-scrolling
* **Given** a Backlogs list with a vertical scrollbar
* **When** a user drags a card to the top 10% or bottom 10% of the list container
* **Then** the list automatically scrolls in that direction.
#### Scenario 7: Accessibility (Keyboard/Non-Drag Fallback)
* **Given** any Work Package card
* **When** a user opens the card's context menu / move dialog
* **Then** they can move it to a different Sprint or Backlog Bucket without using drag and drop.
* **And** while a move is processing, the target list has the `aria-busy="true"` attribute set.
---
### Gap Analysis & Implementation Notes
1. **Drop Rejection Feedback:** If an item cannot be dropped (e.g., restricted type), the drop indicator (gap) must not appear.
2. **Concurrent Modifications:** Handled via Scenario 4 (Revert + Notification).
3. **Visual Source State:** While dragging, the original card should remain in the list with reduced opacity (0.4) to act as a "ghost" placeholder.
4. **Auto-scrolling Threshold:** Defined as the top/bottom 10% of the list's viewport.
5. **Pagination:** Items can only be dropped into currently loaded regions of the list.
### Technical Notes
* Part of the cross-application drag-and-drop epic #DREAM-672: the `sortable-lists` suite built here is the shared DnD foundation, and Backlogs is its first consumer.
* Migrating Backlogs DnD from dragula to Atlassian Pragmatic DnD (#AGILE-251).
* Reusable `sortable-lists` Stimulus primitive in `frontend/src/stimulus/controllers/dynamic/`; Backlogs is the first consumer.
* **Mobile/Touch Support:** Verified that native HTML5 DnD (Pragmatic's default adapter) does not fire `DragEvents` for finger-touch. This requires either polyfilling or a Pointer Events implementation (tracked in #AGILE-293).
* Controller topology: single root per page + leaf controllers for list/item.
* Related: #AGILE-175, #AGILE-181, #AGILE-278, #AGILE-284.
**Out of scope**
* Multi-select and batch move (#AGILE-181).
* Reordering whole Backlogs lists, buckets, or sprints (#AGILE-175).
* Long-press and advanced gestures beyond basic touch drag.
* Keyboard-operable drag-and-drop and screen-reader drag/drop announcements.
**I want to** use drag and drop to move items
**so that** can manage my backlogs, buckets and sprints effectively.
---
### Acceptance Criteria (Refined)
#### Scenario 1: Reordering within the same list
* **Given** a user with "manage backlog/sprint items" permissions
* **When** they drag a Work Package card up or down within its current list
* **Then** a visual drop indicator (highlighted gap) appears at valid drop positions.
* **And When** they drop the card
* **Then** the card instantly moves to the new position (optimistic update).
* **And** the new order is persisted to the server.
* **And** refreshing the page confirms the new order.
#### Scenario 2: Moving between lists
* **Given** a user with "manage backlog/sprint items" permissions
* **When** they drag a card from an Inbox backlog
* **And** hover over an empty Sprint list
* **Then** the empty Sprint list visually indicates it can accept the drop.
* **When** they drop the card
* **Then** the card instantly appears in the Sprint list.
* **And** the move is persisted to the server.
#### Scenario 3: Missing Permissions
* **Given** a user **without** "manage backlog/sprint items" permissions
* **When** they attempt to click and drag a Work Package card
* **Then** the card cannot be picked up (no drag state is initiated).
#### Scenario 4: Optimistic Update Failure (Server Error)
* **Given** a user drags and drops a card to a new position
* **When** the server returns an error (e.g., network failure or concurrent edit)
* **Then** the card reverts to its original position.
* **And** an error flash notice is displayed explaining the failure.
#### Scenario 5: Card Visibility After Move
* **Given** a user's current view filters out closed items
* **When** they drag a card into a Sprint where a workflow rule automatically closes it
* **Then** the card disappears from the view.
* **And** a notification/toast is shown informing the user that the moved item is no longer visible in the current view.
#### Scenario 6: Auto-scrolling
* **Given** a Backlogs list with a vertical scrollbar
* **When** a user drags a card to the top 10% or bottom 10% of the list container
* **Then** the list automatically scrolls in that direction.
#### Scenario 7: Accessibility (Keyboard/Non-Drag Fallback)
* **Given** any Work Package card
* **When** a user opens the card's context menu / move dialog
* **Then** they can move it to a different Sprint or Backlog Bucket without using drag and drop.
* **And** while a move is processing, the target list has the `aria-busy="true"` attribute set.
---
### Gap Analysis & Implementation Notes
1. **Drop Rejection Feedback:** If an item cannot be dropped (e.g., restricted type), the drop indicator (gap) must not appear.
2. **Concurrent Modifications:** Handled via Scenario 4 (Revert + Notification).
3. **Visual Source State:** While dragging, the original card should remain in the list with reduced opacity (0.4) to act as a "ghost" placeholder.
4. **Auto-scrolling Threshold:** Defined as the top/bottom 10% of the list's viewport.
5. **Pagination:** Items can only be dropped into currently loaded regions of the list.
### Technical Notes
* Part of the cross-application drag-and-drop epic #DREAM-672: the `sortable-lists` suite built here is the shared DnD foundation, and Backlogs is its first consumer.
* Migrating Backlogs DnD from dragula to Atlassian Pragmatic DnD (#AGILE-251).
* Reusable `sortable-lists` Stimulus primitive in `frontend/src/stimulus/controllers/dynamic/`; Backlogs is the first consumer.
* **Mobile/Touch Support:** Verified that native HTML5 DnD (Pragmatic's default adapter) does not fire `DragEvents` for finger-touch. This requires either polyfilling or a Pointer Events implementation (tracked in #AGILE-293).
* Controller topology: single root per page + leaf controllers for list/item.
* Related: #AGILE-175, #AGILE-181, #AGILE-278, #AGILE-284.
**Out of scope**
* Multi-select and batch move (#AGILE-181).
* Reordering whole Backlogs lists, buckets, or sprints (#AGILE-175).
* Long-press and advanced gestures beyond basic touch drag.
* Keyboard-operable drag-and-drop and screen-reader drag/drop announcements.