The examples are cumbersome and difficult to comprehend

[crabvk]

Hi. Thank you for the great library.
There's one issue with examples, in my opinion. AFAIK, the purpose on an example is to illustrate one use case by providing a specific instance, specific code that you can easily copy&paste and modify for your task. But the code and components in dnd-kit/stories are too abstract and versatile, so it's difficult to comprehend and get only the parts needed.

[gravitypersists]

Yes, I believe this is often a case of "you did a good job making your code DRY", but now it's impossible to comprehend without significant investment and reverse engineering. I copied some of the example code into my personal workspace to make it easier to work with, but then I realized there was abstracted common components nested in these abstracted common components...

For example, in just setting up a basic column dnd - It took me way too long to figure out why my drag wasn't working. All the events were firing. So I loaded up devtools on this repo's storybook and did some digging, noticing that transforms weren't applying. What I needed to understand was that the examples were setup to map the translate coordinates with essentially:

const { transform } = useDraggable(...)
const style = {
  transform: `translate3d(${transform?.x || 0}px, ${transform?.y || 0}px, 0)`
}
<div style={style}>...</div>

The example code isn't exactly clear on this. It's currently mapping these to css variables within Item.tsx which were setup within Draggable.module.css.

This is pretty basic stuff, if you ask me, and I would say it should be made a bit clearer that this library does not handle setting this up for you. Which I think is a fair assumption to be made since we're essentially taking props out of hooks and spreading them onto our components.

Also, I believe the storybook could use some revamping such that when you "view code" it doesn't just show you this, but what about the example generally makes it unique:

This is an inherently complex library so that's going to be quite difficult to pull off, but it will make lives just a little bit more easier for us until the robots take over. I'm incredibly busy at my job (who isn't) so all I can do now is complain but I'll try and help improve this if I get the chance.

---

For reference, I'd say the code for a simple dnd should look something like:

export default function List() {
  const [identifiers, setIdentifiers] = useState(['a', 'b', 'c']);
  const [activeId, setActiveId] = useState<UniqueIdentifier | null>(null);

  const sensors = useSensors(useSensor(MouseSensor), useSensor(TouchSensor), useSensor(KeyboardSensor));

  return (
    <DndContext
      sensors={sensors}
      onDragStart={({ active }) => ...}
      onDragEnd={({ over }) => ...}
      onDragCancel={() =>  ...}
    >
      <SortableContext items={identifiers} strategy={verticalListSortingStrategy}>
        {identifiers.map((identifier) => (
          <DraggableItem key={identifier} id={identifier} />
        ))}
        <DragOverlay>{activeId && <Item id={activeId} />}</DragOverlay>
      </SortableContext>
    </DndContext>
  );
}

function Item({ id }: { id: string }) {
  return <div>Item {id}</div>
} 

export default function DraggableItem({ id }: { id: string }) {
  const { attributes, listeners, setNodeRef, transform, transition } = useSortable({
    id,
    data: { type: 'section', id },
  });
  const style = {
    transform: `translate3d(${transform?.x || 0}px, ${transform?.y || 0}px, 0)`,
    transition,
  };
  return (
    <div ref={setNodeRef} style={style} {...attributes} {...listeners}>
      <Item id={id} />
    </div>
  );
}

This establishes a few key concepts for the learner (among others):

• you need to track the actively dragged item
• if you want to set a drag overlay, you need to differentiate that from the draggable version of it
• you needs to pass along transform coordinates

Sure, it doesn't have all that fancy stuff the others have, and it's going to lead to a lot of repetitive code that breaks DRY, but it solves the problem of serving the example for the learner really well and that's it's primary purpose as example code.

[MatthieuLJ]

I had the same problem when looking at the code in the stories, but then you can look at the examples in codesandbox, those are much more "bite-size", very well written code, and show a wide diversity of use-cases.