feat(drag-and-drop): cross-list DnD, useDragAndDrop hook, and DataTable integration

[ByronDWall]

Closes #1554

Motivation

DraggableList.Root uses a single hardcoded drag type (nimbus-draggable-list-item) for all instances on a page. Every list accepts every other list's items, with no public API to opt out. Consumers rendering two independent lists — say, a "selected columns" list and an "available filters" list — have no way to prevent items from leaking between them. The getDropOperation callback is hardcoded to "move" and the internally-constructed dragAndDropHooks silently overrides any consumer-supplied value.

The only workaround today is reverting foreign items inside onUpdateItems (which flashes the wrong state) or forking the component entirely.

This PR solves the problem with a dragNamespace prop (option 1 from the issue) and, while doing so, extracts the drag-and-drop wiring into a shared useDragAndDrop hook that also works with DataTable and any other React Aria collection component.

What changed

New useDragAndDrop hook

Rather than fixing DraggableList in isolation, the DnD configuration is extracted into a reusable hook. It wraps React Aria's useDragAndDrop with:

• Namespace isolation — dragNamespace appends a suffix to the internal drag type, so only collections sharing the same namespace can exchange items. Omitting it preserves backward-compatible behavior where all lists interoperate.
• External drop support — onExternalDrop + acceptExternalTypes let a collection accept drops from outside the app (text, files, etc.). resolveDropOperation validates incoming types against acceptExternalTypes before returning the configured operation.
• Outgoing format serialization — serializeDragItem adds custom MIME representations alongside the internal format when items are dragged out.
• Auto-keying — items returned from onExternalDrop without key or id get a crypto.randomUUID() key so React Aria's collection can track them.

State handler factories

Consumers need to wire up insert/append/reorder/remove callbacks. Two factories make this a one-liner:

• createArrayHandlers(setItems, getKey?) — for useState arrays
• createListDataHandlers(list) — for React Aria's useListData

Both return an object meant to be spread into the hook options.

External drop helpers

Six composable utilities for converting raw DropItem[] inside onExternalDrop:

Helper	Accepts	Produces
createItemsFromTextDrop	text/plain (or custom)	{ key, label }
createItemsFromFileDrop	File drops	{ key, label, fileName, fileType, file }
createItemsFromDirectoryDrop	Directory drops	Flattened files with { directory }
createItemsFromJsonDrop	application/json	{ key, label, data }
createItemsFromCsvDrop	text/csv	{ key, label, headers, row }
createItemsFromImageDrop	Image file drops	{ key, label, fileType, objectUrl, file }

DraggableList changes

• New props: dragNamespace, onExternalDrop, acceptExternalTypes, externalDropOperation, serializeDragItem
• Internal implementation now delegates to the shared hook instead of calling React Aria directly
• DraggableList.Root continues to manage its own useListData state; the hook handles the drag-and-drop configuration

DataTable integration

The DataTable previously had no drag-and-drop support. This PR adds:

• Optional dragAndDropHooks prop on both DataTable and DataTable.Table
• When provided, a sticky drag handle column (DragIndicator icon) is automatically prepended
• Sticky column offset cascade handles all combinations of drag + selection + expand columns in base, hover, and pinned row contexts
• draggable="true" on rows suppresses native double-click text selection; a programmatic selection.modify() workaround restores it using caretPositionFromPoint (Chrome/Firefox) with caretRangeFromPoint fallback (Safari)
• Row click handler uses native DOM capture-phase listeners to coexist with React Aria's press handling

Architecture

hooks/use-drag-and-drop/
├── use-drag-and-drop.ts        # Main hook + resolveDropOperation
├── use-drag-and-drop.types.ts  # DragAndDropProps, UseDragAndDropOptions, DragAndDropItemData
├── state-handlers.ts           # createArrayHandlers, createListDataHandlers
├── process-drop-items.ts       # Internal/external item separation + auto-keying
├── external-drop-helpers.ts    # Six composable drop converters
├── index.ts                    # Public barrel export
├── use-drag-and-drop.mdx       # Hook documentation
├── use-drag-and-drop.spec.ts   # Unit tests (63 tests)
├── use-drag-and-drop.stories.tsx
└── utils/
    └── use-drag-and-drop.test-utils.ts

resolveDropOperation is extracted as a pure function so the drop-operation decision logic (internal vs. external type validation vs. cancel) is unit-testable independent of React.

Testing

Unit tests (63 tests in use-drag-and-drop.spec.ts):

• createArrayHandlers — insert, append, reorder, remove, default key extraction, missing key error
• createListDataHandlers — all delegation paths
• processDropItems — internal deserialization, external routing, auto-keying, corrupted JSON
• All six external drop helpers — type filtering, field extraction, edge cases
• resolveDropOperation — internal move/cancel, external type accepted/rejected, operation allowed/denied

Storybook interaction tests:

• Reorder within a single list
• Namespace isolation (reorder alpha, verify beta unchanged)
• Cross-list transfer (drag from source to target)
• DataTable integration (drag handle rendering, keyboard reorder, row click coexistence)

Test plan

• Unit tests pass (pnpm test:dev — 110 tests across 4 files)
• TypeScript compiles cleanly (pnpm typecheck)
• Storybook stories render for useDragAndDrop, DraggableList, and DataTable DnD variants
• Keyboard drag-and-drop works (Enter to grab, Arrow to move, Enter to drop)
• Cross-list transfer moves items between lists sharing a namespace
• Namespace isolation prevents drops between lists with different namespaces
• DataTable drag handles appear when dragAndDropHooks is provided
• Pinned rows + drag column sticky offsets render correctly
• Double-click text selection works on draggable DataTable rows

[changeset-bot]

🦋 Changeset detected

Latest commit: ac2ab7c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@commercetools/nimbus	Minor
@commercetools/nimbus-tokens	Minor
@commercetools/nimbus-icons	Minor
@commercetools/nimbus-design-token-ts-plugin	Minor
@commercetools/nimbus-mcp	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nimbus-documentation	Ready	Preview, Comment	May 29, 2026 2:41pm
nimbus-storybook	Ready	Preview, Comment	May 29, 2026 2:41pm

[github-actions]

Localization reminder: This PR adds or modifies `.i18n.ts` files.

Please create a Jira ticket for the localization manager to initiate translation of any new or updated strings in Transifex. See LOC-1766 as an example.

[github-actions]

Bundle Size Report

_{Last updated: 2026-05-29 14:40:48 UTC}

Package	Format	Current	Baseline	Delta	Status
@commercetools/nimbus	dist	15756.9 KB	15682.8 KB	+0.5%	✅ ok
@commercetools/nimbus-icons	dist	4787.6 KB	4787.6 KB	+0.0%	✅ ok
@commercetools/nimbus-tokens	dist	408.1 KB	408.1 KB	+0.0%	✅ ok

Baseline source: comment-chain

[tylermorrisford]

from claude:

hasSelectedText guard removed unconditionally — regression for non-draggable rows

In data-table.row.tsx, the old handleRowClick path skipped navigation if the user had selected text (!hasSelectedText). That guard is gone now. On any row with onRowClick — draggable or not — a mouse-up after text selection will trigger navigation. The dblclick programmatic-selection workaround only applies to [draggable='true'] rows, so non-draggable rows lose the protection.

But honestly if the row has an onRowClick, shouldn't the navigation or other onRowClick operations take precedence over selecting text?

[tylermorrisford]

one Q, otherwise 💰