@dnd-kit/sortable

Patch Changes

• Updated dependencies [bc588c7, b417f0f, f342d5e]:
  • @dnd-kit/core@6.1.0
  • @dnd-kit/utilities@3.2.2

Patch Changes

• #788 da94c02 Thanks @clauderic! - Bug fixes for React 18 Strict Mode

• Updated dependencies [da94c02]:

  • @dnd-kit/core@6.0.7

Patch Changes

• #792 b6970e7 Thanks @clauderic! - The hasSortableData type-guard that is exported by @dnd-kit/sortable has been updated to also accept the Active and Over interfaces so it can be used in events such as onDragStart, onDragOver, and onDragEnd.

• Updated dependencies [eaa6e12]:

  • @dnd-kit/core@6.0.4

Major Changes

• #755 33e6dd2 Thanks @clauderic! - The UniqueIdentifier type has been updated to now accept either string or number identifiers. As a result, the id property of useDraggable, useDroppable and useSortable and the items prop of <SortableContext> now all accept either string or number identifiers.

  Migration steps

  For consumers that are using TypeScript, import the UniqueIdentifier type to have strongly typed local state:

  + import type {UniqueIdentifier} from '@dnd-kit/core';
  
  function MyComponent() {
  -  const [items, setItems] = useState(['A', 'B', 'C']);
  +  const [items, setItems] = useState<UniqueIdentifier>(['A', 'B', 'C']);
  }
  

  Alternatively, consumers can cast or convert the id property to a string when reading the id property of interfaces such as Active, Over, DroppableContainer and DraggableNode.

  The draggableNodes object has also been converted to a map. Consumers that were reading from the draggableNodes property that is available on the public context of <DndContext> should follow these migration steps:

  - draggableNodes[someId];
  + draggableNodes.get(someId);
  

• #660 30bbd12 Thanks @clauderic! - Changes to the default sortableKeyboardCoordinates KeyboardSensor coordinate getter.

  Better handling of variable sizes

  The default sortableKeyboardCoordinates function now has better handling of lists that have items of variable sizes. We recommend that consumers re-order lists onDragOver instead of onDragEnd when sorting lists of variable sizes via the keyboard for optimal compatibility.

  Better handling of overlapping droppables

  The default sortableKeyboardCoordinates function that is exported from the @dnd-kit/sortable package has been updated to better handle cases where the collision rectangle is overlapping droppable rectangles. For example, for down arrow key, the default function had logic that would only consider collisions against droppables that were below the bottom edge of the collision rect. This was problematic when the collision rect was overlapping droppable rects, because it meant that it's bottom edge was below the top edge of the droppable, and that resulted in that droppable being skipped.

  - collisionRect.bottom > droppableRect.top
  + collisionRect.top > droppableRect.top
  

  This change should be backwards compatible for most consumers, but may introduce regressions in some use-cases, especially for consumers that may have copied the multiple containers examples. There is now a custom sortable keyboard coordinate getter optimized for multiple containers that you can refer to.

Minor Changes

• #748 59ca82b Thanks @clauderic! - Automatic focus management and activator node refs.

  Introducing activator node refs

  Introducing the concept of activator node refs for useDraggable and useSortable. This allows @dnd-kit to handle common use-cases such as restoring focus on the activator node after dragging via the keyboard or only allowing the activator node to instantiate the keyboard sensor.

  Consumers of useDraggable and useSortable may now optionally set the activator node ref on the element that receives listeners:

  import {useDraggable} from '@dnd-kit/core';
  
  function Draggable(props) {
    const {
      listeners,
      setNodeRef,
  +   setActivatorNodeRef,
    } = useDraggable({id: props.id});
  
    return (
      <div ref={setNodeRef}>
        Draggable element
        <button
          {...listeners}
  +       ref={setActivatorNodeRef}
        >
          :: Drag Handle
        </button>
      </div>
    )
  }
  

  It's common for the activator element (the element that receives the sensor listeners) to differ from the draggable node. When this happens, @dnd-kit has no reliable way to get a reference to the activator node after dragging ends, as the original event.target that instantiated the sensor may no longer be mounted in the DOM or associated with the draggable node that was previously active.

  Automatically restoring focus

  Focus management is now automatically handled by @dnd-kit. When the activator event is a Keyboard event, @dnd-kit will now attempt to automatically restore focus back to the first focusable node of the activator node or draggable node.

  If no activator node is specified via the setActivatorNodeRef setter function of useDraggble and useSortable, @dnd-kit will automatically restore focus on the first focusable node of the draggable node set via the setNodeRef setter function of useDraggable and useSortable.

  If you were previously managing focus manually and would like to opt-out of automatic focus management, use the newly introduced restoreFocus property of the accessibility prop of <DndContext>:

  <DndContext
    accessibility={{
  +   restoreFocus: false
    }}
  

• #672 10f6836 Thanks @clauderic! - SortableContext now always requests measuring of droppable containers when its items prop changes, regardless of whether or not dragging is in progress. Measuring will occur if the measuring configuration allows for it.

• #754 224201a Thanks @clauderic! - The <SortableContext> component now optionally accepts a disabled prop to globally disable useSortable hooks rendered within it.

  The disabled prop accepts either a boolean or an object with the following shape:

  interface Disabled {
    draggable?: boolean;
    droppable?: boolean;
  }
  

  The useSortable hook has now been updated to also optionally accept the disabled configuration object to conditionally disable the useDraggable and/or useDroppable hooks used internally.

  Like the strategy prop, the disabled prop defined on the useSortable hook takes precedence over the disabled prop defined on the parent <SortableContext>.

Patch Changes

• #757 e6d544f Thanks @clauderic! - The wasDragging property of animateLayoutChanges now remains true for longer than a single re-render. Before this change, it was possible for the component where useSortable is used to re-render before @dnd-kit is ready to perform the layout animation, causing the animation to be skipped entirely.

• #749 188a450 Thanks @clauderic! - Faster (and safer) equal implementation.

• Updated dependencies [4173087, 59ca82b, 7161f70, a52fba1, 40707ce, a41e5b8, bf30718, a41e5b8, a41e5b8, 035021a, 77e3d44, 5811986, e302bd4, 188a450, 59ca82b, 750d726, 5f3c700, 035021a, e6e242c, 035021a, 33e6dd2, 10f6836, c1b3b5a, 035021a]:

  • @dnd-kit/core@6.0.0
  • @dnd-kit/utilities@3.2.0

Patch Changes

• #642 15a6017 Thanks @vosatom! - Fixed an issue that affected SortableContext performance. The sortedRects property of the SortableContext provider were being recomputed whenever coordinates changed rather than only when the order of the items changed.

• Updated dependencies [b3b185d]:

  • @dnd-kit/core@5.0.2

Major Changes

• #518 6310227 Thanks @clauderic! - Major internal refactor of measuring and collision detection.

  Summary of changes

  Previously, all collision detection algorithms were relative to the top and left points of the document. While this approach worked in most situations, it broke down in a number of different use-cases, such as fixed position droppable containers and trying to drag between containers that had different scroll positions.

  This new approach changes the frame of comparison to be relative to the viewport. This is a major breaking change, and will need to be released under a new major version bump.

  Breaking changes:

  • By default, @dnd-kit now ignores only the transforms applied to the draggable / droppable node itself, but considers all the transforms applied to its ancestors. This should provide the right balance of flexibility for most consumers.
    • Transforms applied to the droppable and draggable nodes are ignored by default, because the recommended approach for moving items on the screen is to use the transform property, which can interfere with the calculation of collisions.
    • Consumers can choose an alternate approach that does consider transforms for specific use-cases if needed by configuring the measuring prop of <DndContext>. Refer to the <Switch> example.
  • Reduced the number of concepts related to measuring from ViewRect, LayoutRect to just a single concept of ClientRect.
    • The ClientRect interface no longer holds the offsetTop and offsetLeft properties. For most use-cases, you can replace offsetTop with top and offsetLeft with left.
    • Replaced the following exports from the @dnd-kit/core package with getClientRect:
      • getBoundingClientRect
      • getViewRect
      • getLayoutRect
      • getViewportLayoutRect
  • Removed translatedRect from the SensorContext interface. Replace usage with collisionRect.
  • Removed activeNodeClientRect on the DndContext interface. Replace with activeNodeRect.

• #569 e7ac3d4 Thanks @clauderic! - Separated context into public and internal context providers. Certain properties that used to be available on the public DndContextDescriptor interface have been moved to the internal context provider and are no longer exposed to consumers:

  interface DndContextDescriptor {
  -  dispatch: React.Dispatch<Actions>;
  -  activators: SyntheticListeners;
  -  ariaDescribedById: {
  -    draggable: UniqueIdentifier;
  -  };
  }
  

  Having two distinct context providers will allow to keep certain internals such as dispatch hidden from consumers.

  It also serves as an optimization until context selectors are implemented in React, properties that change often, such as the droppable containers and droppable rects, the transform value and array of collisions should be stored on a different context provider to limit un-necessary re-renders in useDraggable, useDroppable and useSortable.

  The <InternalContext.Provider> is also reset to its default values within <DragOverlay>. This paves the way towards being able to seamlessly use components that use hooks such as useDraggable and useDroppable as children of <DragOverlay> without causing interference or namespace collisions.

  Consumers can still make calls to useDndContext() to get the active or over properties if they wish to re-render the component rendered within DragOverlay in response to user interaction, since those use the PublicContext

Minor Changes

• #558 f3ad20d Thanks @clauderic! - Refactor of the CollisionDetection interface to return an array of Collisions:

  +export interface Collision {
  +  id: UniqueIdentifier;
  +  data?: Record<string, any>;
  +}
  
  export type CollisionDetection = (args: {
    active: Active;
    collisionRect: ClientRect;
    droppableContainers: DroppableContainer[];
    pointerCoordinates: Coordinates | null;
  -}) => UniqueIdentifier;
  +}) => Collision[];
  

  This is a breaking change that requires all collision detection strategies to be updated to return an array of Collision rather than a single UniqueIdentifier

  The over property remains a single UniqueIdentifier, and is set to the first item in returned in the collisions array.

  Consumers can also access the collisions property which can be used to implement use-cases such as combining droppables in user-land.

  The onDragMove, onDragOver and onDragEnd callbacks are also updated to receive the collisions array property.

  Built-in collision detections such as rectIntersection, closestCenter, closestCorners and pointerWithin adhere to the CollisionDescriptor interface, which extends the Collision interface:

  export interface CollisionDescriptor extends Collision {
    data: {
      droppableContainer: DroppableContainer;
      value: number;
      [key: string]: any;
    };
  }
  

  Consumers can also access the array of collisions in components wrapped by <DndContext> via the useDndContext() hook:

  import {useDndContext} from '@dnd-kit/core';
  
  function MyComponent() {
    const {collisions} = useDndContext();
  }
  

• #561 02edd26 Thanks @clauderic! - Droppable containers now observe the node they are attached to via setNodeRef using ResizeObserver while dragging.

  This behaviour can be configured using the newly introduced resizeObserverConfig property.

  interface ResizeObserverConfig {
    /** Whether the ResizeObserver should be disabled entirely */
    disabled?: boolean;
    /** Resize events may affect the layout and position of other droppable containers.
     * Specify an array of `UniqueIdentifier` of droppable containers that should also be re-measured
     * when this droppable container resizes. Specifying an empty array re-measures all droppable containers.
     */
    updateMeasurementsFor?: UniqueIdentifier[];
    /** Represents the debounce timeout between when resize events are observed and when elements are re-measured */
    timeout?: number;
  }
  

  By default, only the current droppable is scheduled to be re-measured when a resize event is observed. However, this may not be suitable for all use-cases. When an element resizes, it can affect the layout and position of other elements, such that it may be necessary to re-measure other droppable nodes in response to that single resize event. The recomputeIds property can be used to specify which droppable ids should be re-measured in response to resize events being observed.

  For example, the useSortable preset re-computes the measurements of all sortable elements after the element that resizes, so long as they are within the same SortableContext as the element that resizes, since it's highly likely that their layout will also shift.

  Specifying an empty array for recomputeIds forces all droppable containers to be re-measured.

  For consumers that were relyings on the internals of DndContext using useDndContext(), the willRecomputeLayouts property has been renamed to measuringScheduled, and the recomputeLayouts method has been renamed to measureDroppableContainers, and now optionally accepts an array of droppable UniqueIdentifier that should be scheduled to be re-measured.

• #570 1ade2f3 Thanks @clauderic! - Use transition for the active draggable node when keyboard sorting without a <DragOverlay />.

Patch Changes

• #566 d315df0 Thanks @clauderic! - Fixed a bug where sortable item position was not updated when quickly dragging different sortable items.

• Updated dependencies [f3ad20d, 02edd26, c6c67cb, 6310227, e7ac3d4, 528c67e, 02edd26]:

  • @dnd-kit/core@5.0.0
  • @dnd-kit/utilities@3.1.0