Doc updates

Author: clauderic

apps/docs/concepts/drag-drop-manager.mdx

@@ -11,6 +11,7 @@ The `DragDropManager` is the central orchestrator of the drag and drop system. I
 ```js
 import {DragDropManager} from '@dnd-kit/dom';
 
+// Create a manager instance
 const manager = new DragDropManager();
 
 // Create draggable and droppable elements
@@ -37,66 +38,66 @@ import {
 } from '@dnd-kit/dom';
 
 const manager = new DragDropManager({
-  // Custom sensors for detecting drag interactions
+  // Sensors detect drag interactions
   sensors: [
-    PointerSensor,
-    KeyboardSensor,
+    PointerSensor,  // Handles mouse and touch
+    KeyboardSensor, // Enables keyboard navigation
   ],
 
-  // Plugins to extend functionality
+  // Plugins extend functionality
   plugins: [
-    AutoScroller,
-    Accessibility,
+    AutoScroller,   // Automatic scrolling during drag
+    Accessibility,  // ARIA attributes management
   ],
 
-  // Modifiers to customize drag behavior
+  // Modifiers customize drag behavior
   modifiers: [
-    restrictToWindow,
+    restrictToWindow, // Keeps dragged items within window bounds
   ],
 });
 ```
 
 ## Default Configuration
 
-By default, the manager includes:
+The manager includes these defaults out of the box:
 
 ### Sensors
-- `PointerSensor`: Handles mouse and touch interactions with:
-  - Mouse: Immediate activation on drag handle
-  - Touch: 250ms delay with 5px tolerance
+- `PointerSensor`: Handles mouse and touch interactions
+  - Mouse: Activates immediately on drag handle
+  - Touch: 250ms delay with 5px movement tolerance
   - Other pointers: 200ms delay with 5px distance threshold
 
-- `KeyboardSensor`: Enables keyboard navigation
+- `KeyboardSensor`: Enables keyboard navigation with arrow keys
 
 ### Plugins
-- `Accessibility`: Manages ARIA attributes
-- `AutoScroller`: Handles automatic scrolling
-- `Cursor`: Updates cursor styles
-- `Feedback`: Manages drag feedback
+- `Accessibility`: Manages ARIA attributes and announcements for screen readers
+- `AutoScroller`: Scrolls containers when dragging near edges
+- `Cursor`: Updates cursor appearance during drag
+- `Feedback`: Controls visual feedback during drag
 - `PreventSelection`: Prevents text selection while dragging
-- `ScrollListener`: Tracks scroll events
+- `ScrollListener`: Monitors scroll events during drag
 - `Scroller`: Handles programmatic scrolling
 
 ## Events
 
-The manager's `monitor` property allows you to listen for drag and drop events:
+The manager's `monitor` lets you observe drag and drop events:
 
 ```js
-// Listen for when dragging starts
+// Observe drag start
 manager.monitor.addEventListener('beforedragstart', (event) => {
-  // Can prevent the drag from starting
+  // Optionally prevent dragging
   if (shouldPreventDrag(event.operation.source)) {
     event.preventDefault();
   }
 });
 
-// Listen for drag movement
+// Track movement
 manager.monitor.addEventListener('dragmove', (event) => {
   const {source, position} = event.operation;
   console.log(`Dragging ${source.id} to ${position.current}`);
 });
 
-// Listen for collisions with droppable targets
+// Detect collisions
 manager.monitor.addEventListener('collision', (event) => {
   const [firstCollision] = event.collisions;
   if (firstCollision) {
@@ -117,29 +118,28 @@ manager.monitor.addEventListener('dragend', (event) => {
 
 | Event | Description | Preventable | Data |
 |-------|-------------|-------------|------|
-| `beforedragstart` | Fired before dragging begins | Yes | `operation` |
-| `dragstart` | Fired when dragging starts | No | `operation`, `nativeEvent` |
-| `dragmove` | Fired when dragging element moves | Yes | `operation`, `to`, `by`, `nativeEvent` |
-| `dragover` | Fired when hovering over a droppable | Yes | `operation` |
-| `collision` | Fired when colliding with droppables | Yes | `collisions` |
-| `dragend` | Fired when dragging ends | No | `operation`, `canceled`, `nativeEvent` |
+| `beforedragstart` | Fires before drag begins | Yes | `operation` |
+| `dragstart` | Fires when drag starts | No | `operation`, `nativeEvent` |
+| `dragmove` | Fires during movement | Yes | `operation`, `to`, `by`, `nativeEvent` |
+| `dragover` | Fires when over a droppable | Yes | `operation` |
+| `collision` | Fires on droppable collision | Yes | `collisions` |
+| `dragend` | Fires when drag ends | No | `operation`, `canceled`, `nativeEvent` |
 
 ## Registration
 
-The manager's `registry` handles registration of draggable and droppable elements:
+The manager's `registry` tracks draggable and droppable elements:
 
 ```js
-// Manual registration
+// Manual registration when needed
 const cleanup = manager.registry.register(draggable);
 
-// Later cleanup
+// Cleanup when done
 cleanup();
-
 // Or unregister directly
 manager.registry.unregister(draggable);
 ```
 
-Elements are automatically registered when created with a manager reference:
+Elements auto-register when created with a manager reference:
 
 ```js
 // Auto-registers with manager
@@ -154,11 +154,11 @@ const droppable = new Droppable({
   element,
 }, manager);
 
-// Prevent auto-registration
+// Opt out of auto-registration
 const draggable = new Draggable({
   id: 'draggable-1',
   element,
-  register: false // Prevent auto-registration
+  register: false
 }, manager);
 ```
 
@@ -184,7 +184,7 @@ The `DragDropManager` constructor accepts the following configuration:
 
 The manager instance provides these key properties:
 
-- `registry`: Registry of all draggable and droppable elements
+- `registry`: Tracks active elements and extensions
   - `draggables`: Map of registered draggable elements
   - `droppables`: Map of registered droppable elements
   - `plugins`: Registry of active plugins
@@ -198,11 +198,11 @@ The manager instance provides these key properties:
   - `status`: Current operation status
   - `canceled`: Whether operation was canceled
 
-- `monitor`: Event monitor for drag operations
-  - `addEventListener`: Register event listener
-  - `removeEventListener`: Remove event listener
+- `monitor`: Event system
+  - `addEventListener`: Add event listener
+  - `removeEventListener`: Remove listener
 
-- `renderer`: Handles visual updates during drag operations
+- `renderer`: Integration with asynchronous renderers such as React.
 
 ### Methods
 

apps/docs/concepts/draggable.mdx

@@ -45,6 +45,7 @@ By default, the entire element can be used to initiate dragging. You can restric
 const element = document.createElement('div');
 const handle = document.createElement('div');
 handle.classList.add('handle');
+handle.innerHTML = '⋮'; // Three dots menu icon for drag handle
 
 element.appendChild(handle);
 
@@ -64,11 +65,8 @@ You can assign types to draggable elements to restrict which [droppable targets]
 const draggable = new Draggable({
   id: 'draggable-1',
   element,
-  type: 'item',
+  type: 'item', // Only droppables accepting 'item' type will be valid targets
 }, manager);
-
-// Only droppable targets that accept 'item' type
-// will allow this element to be dropped
 ```
 
 ## Feedback
@@ -84,10 +82,10 @@ const draggable = new Draggable({
 ```
 
 Available feedback options:
-- `'default'`: The original element moves with the drag
-- `'clone'`: A copy of the element stays in place while the original moves
-- `'move'`: The element moves without a placeholder
-- `'none'`: No visual feedback
+- `'default'`: The original element moves with the drag (best for most cases)
+- `'clone'`: A copy of the element stays in place while the original moves (good for drag-to-copy)
+- `'move'`: The element moves without a placeholder (minimal visual feedback)
+- `'none'`: No visual feedback (useful for custom drag overlays)
 
 ## API Reference
 
@@ -104,15 +102,15 @@ The `Draggable` class accepts the following arguments:
 </ParamField>
 
 <ParamField path="handle" type="Element">
-  Optionally specify a drag handle element. If not provided, the entire element will be draggable. See [drag handles](#drag-handles).
+  Optionally specify a drag handle element. If not provided, the entire element will be draggable. See [drag handles](#handles).
 </ParamField>
 
 <ParamField path="type" type="string | number | Symbol">
   Optionally assign a type to restrict which droppable targets can accept this element. See [types](#types).
 </ParamField>
 
 <ParamField path="feedback" type="'default' | 'clone' | 'move' | 'none'">
-  Specify how the element should behave while being dragged. See [drag feedback](#drag-feedback).
+  Specify how the element should behave while being dragged. See [feedback](#feedback).
 </ParamField>
 
 <ParamField path="disabled" type="boolean">
@@ -152,4 +150,4 @@ The `Draggable` instance provides these key properties:
 
 - `register()`: Register this draggable with the manager
 - `unregister()`: Remove this draggable from the manager
-- `destroy()`: Clean up this draggable instance
+- `destroy()`: Clean up this draggable instance and remove all listeners

apps/docs/concepts/droppable.mdx

@@ -27,6 +27,13 @@ const droppable = new Droppable({
 }, manager);
 
 document.body.appendChild(element);
+
+// Listen for drop events
+manager.monitor.addEventListener('dragend', (event) => {
+  if (event.operation.target?.id === droppable.id) {
+    console.log('Item dropped!', event.operation.source);
+  }
+});
 ```
 
 ## Accepting Specific Types
@@ -63,7 +70,7 @@ const droppable = new Droppable({
 
 By default, the `Droppable` class uses rectangle intersection to detect when draggable elements are over the drop target:
 
-<img src="/images/droppable/shape-intersection.svg" />
+<img src="/images/droppable/shape-intersection.svg" alt="Rectangle intersection collision detection" />
 
 You can customize this behavior with different collision detection algorithms:
 
@@ -82,13 +89,13 @@ const droppable = new Droppable({
 }, manager);
 ```
 
-For example, the `closestCenter` detector will detect collisions based on the distance between the center points:
+For example, the `closestCenter` detector will detect collisions based on the distance between the center points, which is ideal for card stacking:
 
-<img src="/images/droppable/closest-center.svg" />
+<img src="/images/droppable/closest-center.svg" alt="Closest center collision detection" />
 
 ### Collision Priority
 
-When multiple droppable targets overlap, you can set priority to determine which one should receive the drop:
+When multiple droppable targets overlap, you can set priority to determine which one should receive the drop. This is particularly useful for nested containers:
 
 ```js
 const container = new Droppable({
@@ -124,14 +131,14 @@ The `Droppable` class accepts the following arguments:
 
 <ParamField path="collisionDetector" type="CollisionDetector">
   A function to determine when draggable elements are over this target. See [collision detection](#collision-detection) for built-in options, such as:
-  - `shapeIntersection`
-  - `pointerIntersection`
-  - `closestCenter`
-  - `directionBiased`
+  - `shapeIntersection`: Default, uses rectangle intersection
+  - `pointerIntersection`: Uses pointer position for precise detection
+  - `closestCenter`: Uses center point distance, ideal for card stacking
+  - `directionBiased`: Considers drag direction, useful for sortable lists
 </ParamField>
 
 <ParamField path="collisionPriority" type="number">
-  Priority level when multiple droppable targets overlap. See [collision priority](#collision-priority) for more details.
+  Priority level when multiple droppable targets overlap. Higher numbers take precedence. See [collision priority](#collision-priority) for more details.
 </ParamField>
 
 <ParamField path="disabled" type="boolean">
@@ -163,4 +170,4 @@ The `Droppable` instance provides these key properties:
 - `refreshShape()`: Recalculate the target's dimensions
 - `register()`: Register this target with the manager
 - `unregister()`: Remove this target from the manager
-- `destroy()`: Clean up this droppable instance
+- `destroy()`: Clean up this droppable instance and remove all listeners

apps/docs/overview.mdx

@@ -1,6 +1,6 @@
 ---
 title: Overview
-description: 'Learn how to build drop interfaces with <span class="inline-logo">**dnd kit**</span>'
+description: 'Learn how to build drag and drop interfaces with <span class="inline-logo">**dnd kit**</span>'
 ---
 
 <img