fix: Limit auto-scroll to the nearest scroll container when dragging sortable list items (#5228)

Author: ernst-dev

pages/list/sortable-sticky-drawer-autoscroll.page.tsx

@@ -0,0 +1,101 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React, { useContext, useState } from 'react';
+
+import { Box, List, SegmentedControl } from '~components';
+
+import AppContext, { AppContextType } from '../app/app-context';
+import { SimplePage } from '../app/templates';
+
+type Layout = 'drawer-scroller' | 'drawer' | 'page';
+
+type PageContext = React.Context<AppContextType<{ layout: Layout }>>;
+
+interface Item {
+  id: string;
+  content: string;
+}
+
+const initialItems: Item[] = Array.from({ length: 30 }, (_, index) => ({
+  id: `item-${index + 1}`,
+  content: `Item ${index + 1}`,
+}));
+
+const outerHeight = 600;
+
+function SortableList() {
+  const [items, setItems] = useState<readonly Item[]>(initialItems);
+  return (
+    <List
+      ariaLabel="Sortable list"
+      items={items}
+      sortable={true}
+      renderItem={item => ({ id: item.id, content: item.content })}
+      onSortingChange={event => setItems(event.detail.items)}
+    />
+  );
+}
+
+function StickyDrawerLayout({ ownScroller }: { ownScroller: boolean }) {
+  return (
+    <div data-testid="outer-scroller" style={{ blockSize: outerHeight, overflow: 'auto', display: 'flex' }}>
+      <div style={{ flex: 1 }}>
+        {Array.from({ length: 150 }, (_, index) => (
+          <Box key={index} padding="xxs">
+            Main content row {index + 1}
+          </Box>
+        ))}
+      </div>
+      <aside
+        data-testid="sticky-drawer"
+        style={{
+          position: 'sticky',
+          insetBlockStart: 0,
+          alignSelf: 'flex-start',
+          inlineSize: 320,
+          blockSize: ownScroller ? outerHeight : undefined,
+          display: 'flex',
+          flexDirection: 'column',
+        }}
+      >
+        <Box variant="h2" padding="s">
+          Drawer
+        </Box>
+        {ownScroller ? (
+          <div data-testid="drawer-list-scroller" style={{ flex: 1, overflow: 'auto' }}>
+            <SortableList />
+          </div>
+        ) : (
+          <SortableList />
+        )}
+      </aside>
+    </div>
+  );
+}
+
+export default function SortableListAutoScrollPage() {
+  const {
+    urlParams: { layout = 'drawer-scroller' },
+    setUrlParams,
+  } = useContext(AppContext as PageContext);
+  return (
+    <SimplePage
+      title="Sortable list auto-scroll"
+      screenshotArea={{}}
+      settings={
+        <SegmentedControl
+          label="Layout"
+          selectedId={layout}
+          onChange={({ detail }) => setUrlParams({ layout: detail.selectedId as Layout })}
+          options={[
+            { id: 'drawer-scroller', text: 'Sticky drawer with own scroller' },
+            { id: 'drawer', text: 'Sticky drawer without own scroller' },
+            { id: 'page', text: 'Page flow' },
+          ]}
+        />
+      }
+    >
+      {layout === 'page' ? <SortableList /> : <StickyDrawerLayout ownScroller={layout === 'drawer-scroller'} />}
+    </SimplePage>
+  );
+}

src/internal/components/sortable-area/index.tsx

@@ -2,14 +2,16 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import React, { useEffect, useRef } from 'react';
-import { DndContext, DragOverlay } from '@dnd-kit/core';
+import { AutoScrollOptions, DndContext, DragOverlay, TraversalOrder } from '@dnd-kit/core';
 import { arrayMove, SortableContext, useSortable, verticalListSortingStrategy } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
 import clsx from 'clsx';
 
 import { Portal } from '@cloudscape-design/component-toolkit/internal';
 
 import { fireNonCancelableEvent } from '../../events';
+import { isElement, isHTMLElement } from '../../utils/dom';
+import { getFirstScrollableParent } from '../../utils/scrollable-containers';
 import { joinStrings } from '../../utils/strings';
 import { SortableAreaProps } from './interfaces';
 import { EventName } from './keyboard-sensor/utilities/events';
@@ -37,10 +39,12 @@ export default function SortableArea<Item>({
   const isDragging = activeItemId !== null;
   const announcements = useLiveAnnouncements({ items, itemDefinition, isDragging, ...i18nStrings });
   const portalContainer = usePortalContainer();
+  const { autoScroll, setAutoScrollBoundary } = useScopedAutoScroll();
   return (
     <DndContext
       sensors={sensors}
       collisionDetection={collisionDetection}
+      autoScroll={autoScroll}
       accessibility={{
         announcements,
         restoreFocus: false,
@@ -49,8 +53,12 @@ export default function SortableArea<Item>({
           : undefined,
         container: portalContainer ?? undefined,
       }}
-      onDragStart={({ active }) => setActiveItemId(active.id)}
+      onDragStart={({ active, activatorEvent }) => {
+        setAutoScrollBoundary(activatorEvent.target);
+        setActiveItemId(active.id);
+      }}
       onDragEnd={event => {
+        setAutoScrollBoundary(null);
         setActiveItemId(null);
         const { active, over } = event;
         if (over && active.id !== over.id) {
@@ -60,7 +68,10 @@ export default function SortableArea<Item>({
           fireNonCancelableEvent(onItemsChange, { items: arrayMove([...items], oldIndex, newIndex), movedItem });
         }
       }}
-      onDragCancel={() => setActiveItemId(null)}
+      onDragCancel={() => {
+        setAutoScrollBoundary(null);
+        setActiveItemId(null);
+      }}
     >
       <SortableContext
         disabled={disableReorder}
@@ -110,6 +121,26 @@ export default function SortableArea<Item>({
   );
 }
 
+// dnd-kit auto-scrolls every scrollable ancestor up to the first fixed-position element, outermost first by default
+// (https://github.com/clauderic/dnd-kit/issues/1893). Restrict it to the sortable area's nearest scroll container so
+// that dragging inside e.g. a sticky drawer does not scroll unrelated outer containers. Without a scrollable ancestor,
+// all containers (including the window) remain eligible.
+function useScopedAutoScroll() {
+  const boundaryRef = useRef<HTMLElement | null>(null);
+  const autoScroll: AutoScrollOptions = {
+    order: TraversalOrder.ReversedTreeOrder,
+    canScroll: element => !boundaryRef.current || boundaryRef.current.contains(element),
+  };
+  const setAutoScrollBoundary = (dragStartTarget: EventTarget | null) => {
+    let element = isElement(dragStartTarget) ? dragStartTarget : null;
+    while (element && !isHTMLElement(element)) {
+      element = element.parentElement;
+    }
+    boundaryRef.current = element ? (getFirstScrollableParent(element) ?? null) : null;
+  };
+  return { autoScroll, setAutoScrollBoundary };
+}
+
 function usePortalContainer() {
   const portalContainerRef = useRef(typeof document !== 'undefined' ? document.createElement('div') : null);
   useEffect(() => {

src/list/__tests__/list-sortable.test.tsx

@@ -1,13 +1,28 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 import React from 'react';
+import { AutoScrollOptions, TraversalOrder } from '@dnd-kit/core';
 import { act, fireEvent, render } from '@testing-library/react';
 
 import TestI18nProvider from '../../../lib/components/i18n/testing';
 import List, { ListProps } from '../../../lib/components/list';
 import createWrapper from '../../../lib/components/test-utils/dom';
 import InternalDragHandleWrapper from '../../../lib/components/test-utils/dom/internal/drag-handle';
 
+const mockDndContextAutoScroll: { current: AutoScrollOptions | undefined } = { current: undefined };
+
+jest.mock('@dnd-kit/core', () => {
+  const actual = jest.requireActual('@dnd-kit/core');
+  const { createElement } = jest.requireActual('react');
+  return {
+    ...actual,
+    DndContext: (props: { autoScroll?: AutoScrollOptions }) => {
+      mockDndContextAutoScroll.current = props.autoScroll;
+      return createElement(actual.DndContext, props);
+    },
+  };
+});
+
 interface Item {
   id: string;
   content: string;
@@ -246,4 +261,87 @@ describe('List - Sortable', () => {
     dragHandle.click({ button: 1 });
     expect(dragWrapper.findVisibleDirectionButtonBlockEnd()).toBeFalsy();
   });
+
+  describe('auto-scroll', () => {
+    const interact = (action: () => void) =>
+      act(async () => {
+        action();
+        await new Promise(resolve => setTimeout(resolve, 0));
+      });
+    const canAutoScroll = (element: Element) => mockDndContextAutoScroll.current!.canScroll!(element);
+
+    function renderInScrollContainers({ innerScrolls }: { innerScrolls: boolean }) {
+      const { container } = render(
+        <div data-testid="outer" style={{ overflowY: 'auto' }}>
+          <div data-testid="inner" style={{ overflowY: 'auto' }}>
+            <ControlledList
+              items={defaultItems}
+              renderItem={item => ({ id: item.id, content: item.content })}
+              sortable={true}
+            />
+          </div>
+        </div>
+      );
+      const outer = container.querySelector<HTMLElement>('[data-testid="outer"]')!;
+      const inner = container.querySelector<HTMLElement>('[data-testid="inner"]')!;
+      // jsdom has no layout, so make the containers overflow explicitly.
+      const overflowing = innerScrolls ? [outer, inner] : [];
+      for (const element of overflowing) {
+        Object.defineProperty(element, 'scrollHeight', { configurable: true, value: 1000 });
+        Object.defineProperty(element, 'clientHeight', { configurable: true, value: 100 });
+      }
+      const list = createWrapper(container).findList()!;
+      const item = list.findItemById('item1')!.getElement();
+      const handle = list.findItemById('item1')!.findDragHandle()!.getElement();
+      return { outer, inner, item, handle };
+    }
+
+    test('checks the innermost scroll container first', () => {
+      renderInScrollContainers({ innerScrolls: true });
+      expect(mockDndContextAutoScroll.current!.order).toBe(TraversalOrder.ReversedTreeOrder);
+    });
+
+    test('only auto-scrolls the nearest scroll container and its descendants while dragging', async () => {
+      const { outer, inner, item, handle } = renderInScrollContainers({ innerScrolls: true });
+
+      await interact(() => pressKey(handle, 'Space'));
+
+      expect(canAutoScroll(inner)).toBe(true);
+      expect(canAutoScroll(item)).toBe(true);
+      expect(canAutoScroll(outer)).toBe(false);
+      expect(canAutoScroll(document.documentElement)).toBe(false);
+
+      await interact(() => pressKey(handle, 'Space'));
+
+      expect(canAutoScroll(outer)).toBe(true);
+      expect(canAutoScroll(document.documentElement)).toBe(true);
+    });
+
+    test('keeps every container eligible for auto-scroll when the list has no scrollable ancestor', async () => {
+      const { outer, inner, handle } = renderInScrollContainers({ innerScrolls: false });
+
+      await interact(() => pressKey(handle, 'Space'));
+
+      expect(canAutoScroll(inner)).toBe(true);
+      expect(canAutoScroll(outer)).toBe(true);
+      expect(canAutoScroll(document.documentElement)).toBe(true);
+
+      await interact(() => pressKey(handle, 'Escape'));
+    });
+
+    test('limits auto-scroll when the drag starts on the drag handle icon and stops limiting it on cancel', async () => {
+      const { outer, inner, handle } = renderInScrollContainers({ innerScrolls: true });
+      const icon = handle.querySelector('svg')!;
+      expect(icon).not.toBeNull();
+
+      await interact(() => fireEvent.click(icon));
+
+      expect(canAutoScroll(inner)).toBe(true);
+      expect(canAutoScroll(outer)).toBe(false);
+
+      await interact(() => pressKey(handle, 'Escape'));
+
+      expect(canAutoScroll(outer)).toBe(true);
+    });
+  });
 });