Improve drag and drop for granular changes follow ons

apps/demo/app/[...puckPath]/client.tsx

@@ -27,6 +27,13 @@ export function Client({ path, isEdit }: { path: string; isEdit: boolean }) {
   if (!isClient) return null;
 
   const params = new URL(window.location.href).searchParams;
+  const requestedDndBehavior = params.get("dndBehavior");
+  const dndBehavior =
+    requestedDndBehavior === "auto" ||
+    requestedDndBehavior === "fluid" ||
+    requestedDndBehavior === "static"
+      ? requestedDndBehavior
+      : undefined;
 
   if (isEdit) {
     return (
@@ -42,6 +49,9 @@ export function Client({ path, isEdit }: { path: string; isEdit: boolean }) {
           iframe={{
             enabled: params.get("disableIframe") === "true" ? false : true,
           }}
+          dnd={{
+            behavior: dndBehavior,
+          }}
           fieldTransforms={{
             userField: ({ value }) => value, // Included to check types
           }}

apps/docs/pages/docs/api-reference/components/puck.mdx

@@ -139,10 +139,19 @@ Configure drag-and-drop behavior.
 
 #### dnd params
 
-| Param                                       | Example                    | Type    | Status |
-| ------------------------------------------- | -------------------------- | ------- | ------ |
-| [`disableAutoScroll`](#disableautoscroll)   | `disableAutoScroll: true`  | boolean | -      |
-| [`disableOutlineDrag`](#disableoutlinedrag) | `disableOutlineDrag: true` | boolean | -      |
+| Param                                       | Example                    | Type                            | Status |
+| ------------------------------------------- | -------------------------- | ------------------------------- | ------ |
+| [`behavior`](#behavior)                     | `behavior: "static"`       | `"auto" \| "fluid" \| "static"` | -      |
+| [`disableAutoScroll`](#disableautoscroll)   | `disableAutoScroll: true`  | boolean                         | -      |
+| [`disableOutlineDrag`](#disableoutlinedrag) | `disableOutlineDrag: true` | boolean                         | -      |
+
+##### `behavior`
+
+Control animation behavior while dragging. Defaults to `"auto"`.
+
+- `"auto"` (default): Use fluid behavior within a slot, then switch to static behavior when dragging an item between slots or inserting a new component.
+- `"fluid"`: Move the item during a drag, animating other items out of the way.
+- `"static"`: Freeze the item in-place during a drag, showing a line placeholder at the drop destination.
 
 ##### `disableAutoScroll`
 

apps/docs/pages/docs/api-reference/theming/global.mdx

@@ -40,7 +40,7 @@ CSS properties for theming the entire Puck user interface.
 | `--puck-color-focus-ring`                 | <Color>#3479be</Color>                                      | Keyboard focus outlines                             |
 | `--puck-color-selection-bg`               | <Color>color-mix(in srgb, #cfdff0 30%, transparent)</Color> | Slot, drop zone and selected overlay background     |
 | `--puck-color-selection-border`           | <Color>#abc7e5</Color>                                      | Selected and drop zone outline borders              |
-| `--puck-color-insertion-indicator`        | <Color>#6499cf</Color>                                      | Drag-and-drop insertion line in the outline         |
+| `--puck-color-line-placeholder`           | <Color>#6499cf</Color>                                      | Drag-and-drop insertion line                        |
 | `--puck-color-highlight`                  | <Color>#d89aba</Color>                                      | Accent color scale step, not currently consumed     |
 | `--puck-color-bg-disabled`                | <Color>#ababab</Color>                                      | Disabled button background                          |
 | `--puck-color-text-disabled`              | <Color>#404040</Color>                                      | Disabled button text                                |
@@ -121,8 +121,9 @@ CSS properties for theming the entire Puck user interface.
 
 ## Functional
 
-| Token                             | Default                    | Used for                              |
-| --------------------------------- | -------------------------- | ------------------------------------- |
-| `--puck-slot-min-empty-height`    | `128px`                    | Minimum height of empty slots         |
-| `--puck-user-sidebar-left-width`  | `186px–320px (responsive)` | User override for left sidebar width  |
-| `--puck-user-sidebar-right-width` | `186px–320px (responsive)` | User override for right sidebar width |
+| Token                             | Default                    | Used for                                                    |
+| --------------------------------- | -------------------------- | ----------------------------------------------------------- |
+| `--puck-slot-min-empty-height`    | `128px`                    | Minimum height of empty slots                               |
+| `--puck-line-placeholder-width`   | `2px`                      | Drag-and-drop insertion line thickness (canvas and outline) |
+| `--puck-user-sidebar-left-width`  | `186px–320px (responsive)` | User override for left sidebar width                        |
+| `--puck-user-sidebar-right-width` | `186px–320px (responsive)` | User override for right sidebar width                       |

apps/docs/pages/docs/api-reference/theming/outline.mdx

@@ -57,7 +57,7 @@ Defaults shown as `var(--puck-...)` reference [global tokens](/docs/api-referenc
 | `--puck-outline-color-border-hover`    | `var(--puck-color-interactive-subtle)`   | Layer border color on hover              |
 | `--puck-outline-color-bg-selected`     | `var(--puck-color-interactive-subtle)`   | Selected layer background                |
 | `--puck-outline-color-border-selected` | `var(--puck-color-selection-border)`     | Selected layer border color              |
-| `--puck-outline-color-drop-indicator`  | `var(--puck-color-insertion-indicator)`  | Drag-and-drop line indicator color       |
+| `--puck-outline-color-drop-indicator`  | `var(--puck-color-line-placeholder)`     | Drag-and-drop line indicator color       |
 | `--puck-outline-border-width`          | `var(--puck-border-width-regular)`       | Layer border width                       |
 | `--puck-outline-radius`                | `var(--puck-radius-m)`                   | Layer border radius                      |
 | `--puck-outline-font-size`             | `var(--puck-font-size-xxxs)`             | Layer label font size                    |