feat(useDraggable): add public facing hook

[tomdavies73]

FYI: All commits will be squashed into one final commit, with any relevant issues also linked.

Proposed behaviour

This PR introduces a comprehensive drag-and-drop system built on top of Atlassian's Pragmatic Drag & Drop library.

The implementation provides a flexible, reusable solution for creating draggable lists with automatic reordering capabilities.

Consumers can now use the useDraggable hook which will be externally available to make any array of React Elements draggable.

Key Components Added:

Core Architecture:

• DraggableContainer - Main container component that manages drag operations and list state
• DraggableItem - Individual draggable item wrapper with drop target capabilities
• useDraggable - Hook that simplifies usage by wrapping items automatically
• Context providers for sharing state between container and items

Key Features:

Dual Drag Modes:

• continuous - Items reorder in real-time as user drags
• onDrop - Items only reorder when dropped (better performance for large lists)

Smart State Management:

• Automatic list synchronization when items are added/removed
• Rollback to previous state on invalid drops (outside valid targets)
• Tracks original order for reset functionality

Robust ID Handling:

• Automatic unique ID generation for items
• Duplicate ID detection with console warnings
• Parent ID resolution for nested elements

Imperative API:

• Exposed reOrder(itemId, toIndex) method for programmatic moves
• Supports both direct item IDs and child element IDs

Edge Detection:

• Visual feedback for drop zones (top/bottom edges)
• Prevents dropping items onto themselves
• Container boundary validation

Technical Implementation:

• Built on @atlaskit/pragmatic-drag-and-drop for reliable cross-browser support
• Uses React Context for efficient state sharing
• Implements useImperativeHandle for external control

Benefits:

• Developer Experience: Simple hook-based API with sensible defaults
• Flexibility: Supports custom container/item elements and props
• Reliability: Comprehensive error handling and state recovery
• Performance: Efficient updates with minimal re-renders
• Accessibility: Built on proven drag-and-drop foundation, the useImperativeHandle can be used for manual re-ordering. Supporting graceful degradation.

This implementation provides a production-ready drag-and-drop solution that can be easily integrated into existing components while maintaining full control over styling and behavior.

Current behaviour

Currently, consumers have to use third-party draggable libraries to build out draggable functionality. Internally, we use and re-use react-dnd which is now out of support and results in code repetition and complexity.

Checklist

• Commits follow our style guide
• Related issues linked in commit messages if required
• Screenshots are included in the PR if useful
• All themes are supported if required
• Unit tests added or updated if required
• Playwright automation tests added or updated if required
• Storybook added or updated if required
• Translations added or updated (including creating or amending translation keys table in storybook) if required
• Typescript d.ts file added or updated if required
• Related docs have been updated if required

QA

• Tested in provided StackBlitz sandbox/Storybook
• Add new Playwright test coverage if required
• Carbon implementation matches Design System/designs
• UI Tests GitHub check reviewed if required

Additional context

Testing instructions