@noxlovette/material 0.9.1 → 0.9.2

package/claude-skill/material-design/references/motion-guide.md

@@ -54,31 +54,31 @@ Spatial springs overshoot by design (fast spatial most, at damping ratio 0.6); e
 
 ## JS: picking a primitive
 
-| M3 pattern                                                        | Primitive                                                    | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| ----------------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Enter and exit** — a surface appears/leaves within the screen   | `presence(() => open, enterExit.<preset>)`                   | Attachment. Presets: `fade`, `scale` (menus/popovers/tooltips — sets `transform-origin` to bits-ui's anchor side, so never add an `origin-*` class), `slideUp` (snackbar), `dialog`, `sideSheet`, `bottomSheet`. Interruptible: reopening mid-exit retargets from the current value with velocity.                                                                                                                                              |
-| Same, outside bits-ui (element must stay mounted during its exit) | `new Presence(() => open)`                                   | `{#if p.mounted}<div {@attach p.attach(enterExit.x)}>`. Construct during component init. Used by Snackbar, SideSheet, BottomSheet.                                                                                                                                                                                                                                                                                                              |
-| **Container transform** — card → detail, search bar → view        | `containerTransform(update, { from, to })`                   | Motion `animateView()` (View Transition API). `update` swaps the DOM (`async () => { open = true; await tick(); }`); `to` may be a selector for an element that only exists after the update.                                                                                                                                                                                                                                                   |
-| **Forward and backward** — hierarchy levels, wizard steps         | `sharedAxis(update, { target, axis, direction })`            | `axis: 'x' \| 'y' \| 'z'`, `direction: 'forward' \| 'backward'`. `target` is the persistent region whose content changes; omit for the whole page.                                                                                                                                                                                                                                                                                              |
-| **Lateral** — peer screens (tabs, carousels)                      | `lateral(update, { target, direction, axis })`               | Edge-to-edge slide, no fade, along the axis the peers are laid out on: `axis: 'y'` for vertical tabs, a vertical carousel or a top-to-bottom stepper (`forward` = next, pushing up from below). Never on a vertical nav list: that's a drawer, so top level.                                                                                                                                                                                    |
-| **Top level** — unrelated destinations (navigation bar)           | `fadeThrough(update, { target })`                            | Old fades out, new fades in scaling from 92%. The `target` region swaps its box instantly (no slide or resize, so a scroll reset doesn't glide). In SvelteKit, call it from `onNavigate` in the root layout, skip hash-only changes, and fade only the region whose content changed: `main` between rail/navbar destinations, a section's content pane between pages of a nav that stays on screen (the showcase site's root layout does both). |
-| **Skeleton loaders**                                              | `{@attach skeleton}` on the placeholder                      | Pulses until replaced; reveal the content with `presence(…, enterExit.fade)`.                                                                                                                                                                                                                                                                                                                                                                   |
-| **Direct manipulation** — dragging a pane, reordering chips       | `drag()` attachment + `resist()` + a spring on release       | The attachment reports offsets and release velocity; the caller moves things. Release on `fastSpatial` with `velocity` so the throw carries (DraggablePane, ChipGroup). Neighbours making room play FLIP: measure, reorder, `flushSync()`, spring each from its old offset to 0.                                                                                                                                                                |
-| **Several parts moving as one state change** — rail expand        | One number spring written to a CSS variable                  | `animate(from, to, { ...spring, onUpdate })` writes the progress (`--rail-p`, 0–1) and every part interpolates on it in CSS `calc()`: widths, gaps, heights, positions. One spring keeps them in step and an interruption reverses them together. Things that must not be seen mid-change (the rail label's side and typescale) switch at the halfway point while faded out.                                                                    |
-| Anything custom                                                   | `animate(node, keyframes, springTransition(springTokens.x))` | `springTransition` converts a token to Motion's physics spring (`stiffness`/`damping`), which inherits velocity on interruption.                                                                                                                                                                                                                                                                                                                |
+| M3 pattern                                                        | Primitive                                                    | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ----------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Enter and exit** — a surface appears/leaves within the screen   | `presence(() => open, enterExit.<preset>)`                   | Attachment. Presets: `fade`, `scale` (menus/popovers/tooltips — sets `transform-origin` to bits-ui's anchor side, so never add an `origin-*` class), `slideUp` (snackbar), `dialog`, `sideSheet`, `bottomSheet`. Interruptible: reopening mid-exit retargets from the current value with velocity.                                                                                                                                                                                                                                                                                             |
+| Same, outside bits-ui (element must stay mounted during its exit) | `new Presence(() => open)`                                   | `{#if p.mounted}<div {@attach p.attach(enterExit.x)}>`. Construct during component init. Used by Snackbar, SideSheet, BottomSheet.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| **Container transform** — card → detail, search bar → view        | `containerTransform(update, { from, to })`                   | Motion `animateView()` (View Transition API). `update` swaps the DOM (`async () => { open = true; await tick(); }`); `to` may be a selector for an element that only exists after the update.                                                                                                                                                                                                                                                                                                                                                                                                  |
+| **Forward and backward** — hierarchy levels, wizard steps         | `sharedAxis(update, { target, axis, direction })`            | `axis: 'x' \| 'y' \| 'z'`, `direction: 'forward' \| 'backward'`. `target` is the persistent region whose content changes; omit for the whole page.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| **Lateral** — peer screens (tabs, carousels)                      | `lateral(update, { target, direction, axis })`               | Edge-to-edge slide, no fade, along the axis the peers are laid out on: `axis: 'y'` for vertical tabs, a vertical carousel or a top-to-bottom stepper (`forward` = next, pushing up from below). Never on a vertical nav list: that's a drawer, so top level.                                                                                                                                                                                                                                                                                                                                   |
+| **Top level** — unrelated destinations (navigation bar)           | `fadeThrough(update, { target })`                            | Old fades out, new fades in scaling from 92%. The `target` region swaps its box instantly (no slide or resize, so a scroll reset doesn't glide). In SvelteKit, call it from `onNavigate` in the root layout, skip hash-only changes, and fade only the region whose content changed: `main` between rail/navbar destinations, a section's content pane between pages of a nav that stays on screen (the showcase site's root layout does both).                                                                                                                                                |
+| **Skeleton loaders**                                              | `{@attach skeleton}` on the placeholder                      | Pulses until replaced; reveal the content with `presence(…, enterExit.fade)`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| **Direct manipulation** — dragging a pane, reordering chips       | `drag()` attachment + `resist()` + a spring on release       | The attachment reports offsets and release velocity; the caller moves things. Release on `fastSpatial` with `velocity` so the throw carries (DraggablePane, ChipGroup): scale the pointer's velocity by `resistSlope()` when released past an edge, and aim at `position + project(velocity)` (clamped), not the release point, or a flick springs back to where it was let go. Move with `transform`/`translate`, not `left`/`top`, and commit the resting position once on release. Neighbours making room play FLIP: measure, reorder, `flushSync()`, spring each from its old offset to 0. |
+| **Several parts moving as one state change** — rail expand        | One number spring written to a CSS variable                  | `animate(from, to, { ...spring, onUpdate })` writes the progress (`--rail-p`, 0–1) and every part interpolates on it in CSS `calc()`: widths, gaps, heights, positions. One spring keeps them in step and an interruption reverses them together. Things that must not be seen mid-change (the rail label's side and typescale) switch at the halfway point while faded out.                                                                                                                                                                                                                   |
+| Anything custom                                                   | `animate(node, keyframes, springTransition(springTokens.x))` | `springTransition` converts a token to Motion's physics spring (`stiffness`/`damping`), which inherits velocity on interruption.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
 ### Which components must use which pattern
 
 A pattern belongs in a component only when that component owns both states of the change. When the content that changes lives outside the component (a route, an app screen), the app applies the pattern, not the library. Keep this table in sync when a component gains or loses one of these patterns; each primitive's JSDoc in `src/lib/animation/` repeats its own row.
 
-| Pattern                  | Built into (must use it)                                                                                                                                                              | Left to the app                                                      |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| **Enter and exit**       | Dialogue, BottomSheet, SideSheet, Menu, MenuSub, ContextMenu, Popover, Tooltip, LinkPreview, Select, FABMenu, SplitButton, Snackbar, DateField/DateRangeField/TimeField popups        | —                                                                    |
-| **Lateral**              | TabHolder (switching content panels); DateField/DateRangeField (changing the visible month, via `date/calendarMotion.ts`)                                                             | Navigation (`href`) tabs: the route change is the app's              |
-| **Container transform**  | FAB → its `surface` (`FAB.svelte`: a clip-path and colour morph on Motion, not `containerTransform`); `Search` / search `AppBar` bar → `SearchView` (`containerTransform`, both ways) | Card → detail, Carousel item → detail                                |
-| **Forward and backward** | —                                                                                                                                                                                     | Hierarchy levels, wizard steps                                       |
-| **Top level**            | —                                                                                                                                                                                     | Page changes from `Navbar`/`Rail`: they don't own the content region |
-| **Skeleton loaders**     | —                                                                                                                                                                                     | Placeholders for data the app loads                                  |
+| Pattern                  | Built into (must use it)                                                                                                                                                                                                                                      | Left to the app                                                      |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| **Enter and exit**       | Dialogue, BottomSheet, SideSheet, Menu, MenuSub, ContextMenu, Popover, Tooltip, LinkPreview, Select, FABMenu, SplitButton, Snackbar, DateField/DateRangeField/TimeField popups                                                                                | —                                                                    |
+| **Lateral**              | TabHolder (switching content panels); DateField/DateRangeField (changing the visible month, via `date/calendarMotion.ts`)                                                                                                                                     | Navigation (`href`) tabs: the route change is the app's              |
+| **Container transform**  | FAB → its `surface` (`FAB.svelte`: a clip-path and colour morph on Motion, not `containerTransform`); `Search` / search `AppBar` bar → `SearchView` (`containerTransform`, both ways); `DraggablePane` ↔ its minimised pill (`containerTransform`, both ways) | Card → detail, Carousel item → detail                                |
+| **Forward and backward** | —                                                                                                                                                                                                                                                             | Hierarchy levels, wizard steps                                       |
+| **Top level**            | —                                                                                                                                                                                                                                                             | Page changes from `Navbar`/`Rail`: they don't own the content region |
+| **Skeleton loaders**     | —                                                                                                                                                                                                                                                             | Placeholders for data the app loads                                  |
 
 A new component that mounts a surface must use enter/exit; one that pages between peer views (a stepper of equal steps) must use lateral. `Carousel` is not a pager: its motion is the scroll itself, items resizing through keylines. Opening a tapped item into its detail is a container transform the app applies.
 

package/dist/attachments/drag.d.ts

@@ -50,3 +50,15 @@ export declare function drag(getOptions: () => DragOptions): Attachment<HTMLElem
  * extent of the bounds on that axis.
  */
 export declare function resist(value: number, min: number, max: number, size: number): number;
+/**
+ * How fast a `resist`ed value moves per unit of `value` at that point: `1` inside the range,
+ * less and less past an edge. Scales a pointer's release velocity down to the speed the
+ * rubber-banded thing was actually moving at, so the spring it hands over to doesn't fling it.
+ */
+export declare function resistSlope(value: number, min: number, max: number, size: number): number;
+/**
+ * Where something released at `velocity` (px/s) would coast to — add it to the release position
+ * to aim a spring at, so a throw carries on in its direction instead of springing back to where
+ * it was let go.
+ */
+export declare function project(velocity: number): number;

package/dist/attachments/drag.js

@@ -114,8 +114,11 @@ export function drag(getOptions) {
             const onUp = (event) => {
                 if (event.pointerId !== pointerId)
                     return;
-                if (phase === 'dragging')
+                if (phase === 'dragging') {
+                    // Include the release so a pause after the last move does not reuse stale momentum.
+                    record(event);
                     finish(velocity());
+                }
                 else
                     reset();
             };
@@ -215,3 +218,27 @@ export function resist(value, min, max, size) {
         return max + rubberBand(value - max, size);
     return value;
 }
+/**
+ * How fast a `resist`ed value moves per unit of `value` at that point: `1` inside the range,
+ * less and less past an edge. Scales a pointer's release velocity down to the speed the
+ * rubber-banded thing was actually moving at, so the spring it hands over to doesn't fling it.
+ */
+export function resistSlope(value, min, max, size) {
+    const overshoot = value < min ? min - value : value > max ? value - max : 0;
+    if (!overshoot)
+        return 1;
+    return RUBBER_BAND / ((overshoot * RUBBER_BAND) / size + 1) ** 2;
+}
+/*
+  Per-millisecond speed retained by a thrown object coasting to a stop. UIScrollView's `fast`
+  deceleration rate; M3 has no token for this, tune by eye.
+*/
+const THROW_DECELERATION = 0.99;
+/**
+ * Where something released at `velocity` (px/s) would coast to — add it to the release position
+ * to aim a spring at, so a throw carries on in its direction instead of springing back to where
+ * it was let go.
+ */
+export function project(velocity) {
+    return ((velocity / 1000) * THROW_DECELERATION) / (1 - THROW_DECELERATION);
+}

package/dist/components/containers/pane/DraggablePane.stories.svelte

@@ -1,6 +1,13 @@
 <script module lang="ts">
   import { defineMeta } from '@storybook/addon-svelte-csf';
+  import { tick } from 'svelte';
   import DraggablePane from './DraggablePane.svelte';
+  import { containerTransform } from '../../../animation/containerTransform.js';
+  import { Button } from '../../buttons/index.js';
+  import { Card } from '../../cards/index.js';
+  import { DateField } from '../../date/index.js';
+  import { TimeField } from '../../time/index.js';
+  import { Body, Title } from '../../typography/index.js';
 
   const { Story } = defineMeta({
     title: 'Containers/DraggablePane',
@@ -18,6 +25,48 @@
 </script>
 
 <script lang="ts">
+  // "Opened From A Card": which event's pane is open, if any.
+  const days = [
+    { day: 21, events: [] },
+    { day: 22, events: [{ id: 'math', time: '16:00', title: 'Math' }] },
+    { day: 23, events: [] },
+    { day: 24, events: [{ id: 'physics', time: '17:00', title: 'Physics' }] },
+    { day: 25, events: [] }
+  ];
+  const eventsById = Object.fromEntries(days.flatMap((d) => d.events.map((e) => [e.id, e])));
+  let openEvent: string | undefined = $state();
+
+  const eventCard = (id: string) => `[data-story-event="${id}"]`;
+  const EVENT_PANE = '[data-story-event-pane]';
+
+  // As the calendar does it: the clicked card grows into the pane, and closing
+  // shrinks the pane back into the card it came from.
+  function openFrom(id: string) {
+    if (openEvent) {
+      openEvent = id;
+      return;
+    }
+    containerTransform(
+      async () => {
+        openEvent = id;
+        await tick();
+      },
+      { from: eventCard(id), to: EVENT_PANE }
+    );
+  }
+
+  function closePane() {
+    const id = openEvent;
+    if (!id) return;
+    containerTransform(
+      async () => {
+        openEvent = undefined;
+        await tick();
+      },
+      { from: EVENT_PANE, to: eventCard(id) }
+    );
+  }
+
   let boundedEl: HTMLDivElement | undefined = $state();
   let boundedX: number | undefined = $state();
   let boundedY: number | undefined = $state();
@@ -198,3 +247,53 @@
     </p>
   </DraggablePane>
 </Story>
+
+<!--
+  The calendar's case: an event card grows into the edit pane (container
+  transform) and the pane's close button shrinks it back into that card. The
+  date field sits near the pane's right edge, so its picker spills out over
+  the page — it must stack above the pane (`z-layer-popup` over
+  `z-layer-pane`), never under it.
+-->
+<Story
+  name="Opened From A Card"
+  asChild
+  parameters={{ docs: { story: { inline: false, height: '720px' } } }}
+>
+  <div class="gap-spacing-100 p-spacing-300 grid grid-cols-5">
+    {#each days as { day, events } (day)}
+      <Card type="outlined" padding="sm" class="gap-spacing-100 flex min-h-40 flex-col">
+        <Title size="small">{day}</Title>
+        {#each events as event (event.id)}
+          <Card
+            type="filled"
+            padding="sm"
+            data-story-event={event.id}
+            selected={openEvent === event.id}
+            onselect={() => openFrom(event.id)}
+          >
+            <Body size="small">{event.time}</Body>
+            <Title size="small">{event.title}</Title>
+          </Card>
+        {/each}
+      </Card>
+    {/each}
+  </div>
+
+  {#if openEvent}
+    <DraggablePane
+      data-story-event-pane
+      title={`Edit ${eventsById[openEvent].title}`}
+      initialX={32}
+      initialY={96}
+      resizable
+      onClose={closePane}
+    >
+      <div class="gap-spacing-200 flex w-80 flex-col">
+        <DateField label="Date" variant="outlined" />
+        <TimeField label="Start" value={eventsById[openEvent].time} />
+        <Button onclick={closePane}>Save</Button>
+      </div>
+    </DraggablePane>
+  {/if}
+</Story>

package/dist/components/containers/pane/DraggablePane.svelte

@@ -26,12 +26,14 @@ the pane itself stays `position: fixed` and doesn't move with either.
 -->
 <script lang="ts">
   import clsx from 'clsx';
-  import { onMount } from 'svelte';
-  import { animate, type AnimationPlaybackControls } from 'motion';
+  import { onMount, tick } from 'svelte';
+  import { animate, motionValue } from 'motion';
   import { springTokens, springTransition } from '../../../animation/spring.js';
+  import { containerTransform } from '../../../animation/containerTransform.js';
+  import { prefersReducedMotion } from '../../../animation/reducedMotion.js';
   import { Icon, Layer } from '../../../utils/index.js';
   import { ButtonIcon } from '../../buttons/index.js';
-  import { clickOutside, drag, resist } from '../../../attachments/index.js';
+  import { clickOutside, drag, project, resist, resistSlope } from '../../../attachments/index.js';
   import { draggablePane, type ResizeEdge } from './theme.js';
   import { dragPositions } from './dragStore.svelte.js';
   import type { DraggablePaneProps } from './types.js';
@@ -96,22 +98,26 @@ the pane itself stays `position: fixed` and doesn't move with either.
   // regardless of what those props say, silently overriding the safety-net
   // floor a consumer configured. A non-resizable pane keeps the plain
   // `min-w-72` class fallback (unaffected by minWidth/minHeight).
-  const style = $derived(
-    clsx(
-      x !== undefined && `left: ${x}px;`,
-      y !== undefined && `top: ${y}px;`,
-      width !== undefined && `width: ${width}px;`,
-      height !== undefined && `height: ${height}px;`,
-      resizable && `min-width: ${minWidth}px;`,
-      resizable && `min-height: ${minHeight}px;`,
-      capWidth !== undefined && `max-width: ${capWidth}px;`,
-      capHeight !== undefined && `max-height: ${capHeight}px;`
-    )
-  );
+  //
+  // These are `style:` directives, not a `style` string: Svelte sets directives one property at a
+  // time, whereas a changed `style` string replaces the whole inline style and would wipe the
+  // `translate` that `renderOffset` writes outside Svelte.
+  const px = (value: number | undefined, when = true) =>
+    when && value !== undefined ? `${value}px` : undefined;
 
   function persist() {
     if (!persistKey) return;
-    dragPositions.set(persistKey, { x: x ?? initialX, y: y ?? initialY, width, height });
+    const next = { x: x ?? initialX, y: y ?? initialY, width, height };
+    const stored = dragPositions.get(persistKey);
+    // Bounds re-clamps run on every scroll/resize event; only real changes reach localStorage.
+    if (
+      stored?.x === next.x &&
+      stored.y === next.y &&
+      stored.width === next.width &&
+      stored.height === next.height
+    )
+      return;
+    dragPositions.set(persistKey, next);
   }
 
   function boundsRect() {
@@ -250,7 +256,11 @@ the pane itself stays `position: fixed` and doesn't move with either.
   /** Re-clamps the current position/size, and the standing size cap, against `bounds`'s current rect — call whenever that rect may have changed. */
   function recomputeBounds() {
     updateCaps();
-    moveTo(x ?? initialX, y ?? initialY);
+    // A drag settles against the fresh bounds on release; a running spring is retargeted
+    // rather than having its resting position yanked out from under it.
+    if (dragging) return;
+    if (settling()) settleTo(x ?? initialX, y ?? initialY);
+    else moveTo(x ?? initialX, y ?? initialY);
     if (width !== undefined || height !== undefined) nudgeResize('se', 0, 0);
   }
 
@@ -273,7 +283,10 @@ the pane itself stays `position: fixed` and doesn't move with either.
     window.addEventListener('resize', recomputeBounds);
     return () => {
       window.removeEventListener('resize', recomputeBounds);
-      stopSettle();
+      offRenderX();
+      offRenderY();
+      offsetX.destroy();
+      offsetY.destroy();
     };
   });
 
@@ -308,47 +321,85 @@ the pane itself stays `position: fixed` and doesn't move with either.
 
   /*
     Expressive drag: the pane tracks the pointer 1:1 (direct manipulation never lags behind a
-    spring), rubber-bands past `bounds` instead of hitting a wall, and on release springs back
-    inside on the fast spatial spring, carrying the pointer's velocity. Keyboard nudges glide on
-    the same spring. Grabbing the pane mid-spring stops it where it is.
+    spring), rubber-bands past `bounds` instead of hitting a wall, and on release is thrown: it
+    springs, on the fast spatial spring and at the speed it was really moving, to where the throw
+    would coast to, clamped inside `bounds`. Keyboard nudges glide on the same spring. Grabbing the
+    pane mid-spring stops it where it is.
+
+    `x`/`y` (left/top) are where the pane rests, and change only when it comes to rest somewhere
+    new. The motion in between is a translate offset from there, written straight to the element
+    (`renderOffset`), so a frame of drag or spring never lays the page out, re-renders the
+    component, or hands a parent bound to `x`/`y` a new value.
   */
   const SETTLE_SPRING = springTransition(springTokens.fastSpatial);
 
-  let settleX: AnimationPlaybackControls | undefined;
-  let settleY: AnimationPlaybackControls | undefined;
-  /** Where the running spring is headed; undefined once it's done or stopped. */
-  let settleTarget: { x: number; y: number } | undefined;
+  const offsetX = motionValue(0);
+  const offsetY = motionValue(0);
+
+  function renderOffset() {
+    if (!panelEl) return;
+    const ox = offsetX.get();
+    const oy = offsetY.get();
+    panelEl.style.translate = ox || oy ? `${ox}px ${oy}px` : '';
+  }
+  const offRenderX = offsetX.on('change', renderOffset);
+  const offRenderY = offsetY.on('change', renderOffset);
+
+  const settling = () => offsetX.isAnimating() || offsetY.isAnimating();
 
   function stopSettle() {
-    settleX?.stop();
-    settleY?.stop();
-    settleTarget = undefined;
+    offsetX.stop();
+    offsetY.stop();
   }
 
-  /** Springs the pane to `target` (clamped), starting with `velocity` px/s. */
-  function settleTo(targetX: number, targetY: number, velocity = { x: 0, y: 0 }) {
+  /** Makes where the pane is on screen right now its resting position, with no offset. */
+  function settleInPlace() {
     stopSettle();
+    const ox = offsetX.get();
+    const oy = offsetY.get();
+    if (!ox && !oy) return;
+    offsetX.jump(0);
+    offsetY.jump(0);
+    moveTo((x ?? initialX) + ox, (y ?? initialY) + oy);
+  }
+
+  /**
+   * Springs the pane to `target` (clamped) from wherever it is on screen, starting at `velocity`
+   * px/s — by default the velocity it's already moving at, so a retarget mid-flight is seamless.
+   */
+  function settleTo(
+    targetX: number,
+    targetY: number,
+    velocity = { x: offsetX.getVelocity(), y: offsetY.getVelocity() }
+  ) {
+    const fromX = (x ?? initialX) + offsetX.get();
+    const fromY = (y ?? initialY) + offsetY.get();
     const next = clamp(targetX, targetY);
-    const fromX = x ?? initialX;
-    const fromY = y ?? initialY;
-    settleTarget = next;
-    settleX = animate(fromX, next.x, {
-      ...SETTLE_SPRING,
-      velocity: velocity.x,
-      onUpdate: (value) => (x = value),
-      onComplete: () => (settleTarget = undefined)
-    });
-    settleY = animate(fromY, next.y, {
-      ...SETTLE_SPRING,
-      velocity: velocity.y,
-      onUpdate: (value) => (y = value)
-    });
-    // Persist the resting position up front — the spring only animates towards it.
-    if (persistKey) dragPositions.set(persistKey, { x: next.x, y: next.y, width, height });
+    // The target becomes the resting position straight away and the offset takes up the
+    // difference, so the pane doesn't move this frame; the spring then runs the offset to 0.
+    x = next.x;
+    y = next.y;
+    persist();
+    offsetX.jump(fromX - next.x);
+    offsetY.jump(fromY - next.y);
+    // Under reduced motion there is no spatial travel: the pane is simply where it lands.
+    if (prefersReducedMotion()) {
+      offsetX.jump(0);
+      offsetY.jump(0);
+      return;
+    }
+    animate(offsetX, 0, { ...SETTLE_SPRING, velocity: velocity.x });
+    animate(offsetY, 0, { ...SETTLE_SPRING, velocity: velocity.y });
   }
 
+  // Captured once per drag, so a pointer move reads no layout.
+  let restX = 0;
+  let restY = 0;
   let originX = 0;
   let originY = 0;
+  let pointerX = 0;
+  let pointerY = 0;
+  let range = { minX: 0, maxX: 0, minY: 0, maxY: 0, width: 0, height: 0 };
 
   // Pointer plumbing (capture, release velocity) and the rubber-band come from the shared drag
   // attachment; this only positions the pane.
@@ -357,22 +408,78 @@ the pane itself stays `position: fixed` and doesn't move with either.
     onStart: () => {
       stopSettle();
       dragging = true;
-      originX = x ?? initialX;
-      originY = y ?? initialY;
+      restX = x ?? initialX;
+      restY = y ?? initialY;
+      originX = pointerX = restX + offsetX.get();
+      originY = pointerY = restY + offsetY.get();
+      const rect = boundsRect();
+      const min = clamp(-Infinity, -Infinity);
+      const max = clamp(Infinity, Infinity);
+      range = {
+        minX: min.x,
+        maxX: max.x,
+        minY: min.y,
+        maxY: max.y,
+        width: rect.right - rect.left,
+        height: rect.bottom - rect.top
+      };
     },
     onMove: (offset) => {
-      const rect = boundsRect();
-      const { x: minX, y: minY } = clamp(-Infinity, -Infinity);
-      const { x: maxX, y: maxY } = clamp(Infinity, Infinity);
-      x = resist(originX + offset.x, minX, maxX, rect.right - rect.left);
-      y = resist(originY + offset.y, minY, maxY, rect.bottom - rect.top);
+      pointerX = originX + offset.x;
+      pointerY = originY + offset.y;
+      offsetX.set(resist(pointerX, range.minX, range.maxX, range.width) - restX);
+      offsetY.set(resist(pointerY, range.minY, range.maxY, range.height) - restY);
     },
     onEnd: (velocity) => {
       dragging = false;
-      settleTo(x ?? initialX, y ?? initialY, velocity);
+      // Past an edge the pane only moved at the rubber-banded share of the pointer's speed.
+      const vx = velocity.x * resistSlope(pointerX, range.minX, range.maxX, range.width);
+      const vy = velocity.y * resistSlope(pointerY, range.minY, range.maxY, range.height);
+      const atX = restX + offsetX.get();
+      const atY = restY + offsetY.get();
+      settleTo(atX + project(vx), atY + project(vy), { x: vx, y: vy });
     }
   }));
 
+  /*
+    Minimising and restoring are an M3 container transform: the pane's surface morphs into the
+    pill and back. Only the pane's own buttons animate it; a consumer driving the bound
+    `collapsed` directly swaps the two instantly, since the transition has to snapshot the old
+    state before the change.
+  */
+  const uid = $props.id();
+  let pillEl: HTMLButtonElement | undefined = $state();
+
+  function setCollapsed(next: boolean) {
+    settleInPlace();
+    const from = next ? panelEl : pillEl;
+    if (!from || typeof document === 'undefined') {
+      collapsed = next;
+      return;
+    }
+    containerTransform(
+      async () => {
+        collapsed = next;
+        await tick();
+      },
+      {
+        from,
+        to: next ? `[data-draggable-pane-pill="${uid}"]` : `[data-draggable-pane="${uid}"]`
+      }
+    ).then(
+      () => {},
+      () => (collapsed = next)
+    );
+  }
+
+  // The pane unmounts while collapsed; it comes back at its resting position, with no offset.
+  $effect(() => {
+    if (!collapsed) return;
+    stopSettle();
+    offsetX.jump(0);
+    offsetY.jump(0);
+  });
+
   const NUDGE = 8;
 
   function onKeydown(event: KeyboardEvent) {
@@ -387,9 +494,9 @@ the pane itself stays `position: fixed` and doesn't move with either.
     const delta = deltas[event.key];
     if (!delta) return;
     event.preventDefault();
-    // Retargets a running nudge, so holding an arrow key glides instead of stepping.
-    const from = settleTarget ?? clamp(x ?? initialX, y ?? initialY);
-    settleTo(from.x + delta[0], from.y + delta[1]);
+    // Steps from the resting position, which a running spring is already headed for, so a held
+    // arrow key retargets it and glides instead of stepping.
+    settleTo((x ?? initialX) + delta[0], (y ?? initialY) + delta[1]);
   }
 
   let resizeStartClientX = 0;
@@ -403,6 +510,7 @@ the pane itself stays `position: fixed` and doesn't move with either.
     return (event: PointerEvent) => {
       if (!resizable) return;
       event.stopPropagation();
+      settleInPlace();
       resizeDir = dir;
       resizeStartClientX = event.clientX;
       resizeStartClientY = event.clientY;
@@ -465,6 +573,7 @@ the pane itself stays `position: fixed` and doesn't move with either.
       const delta = deltas[event.key];
       if (!delta) return;
       event.preventDefault();
+      settleInPlace();
       nudgeResize(dir, delta[0], delta[1]);
     };
   }
@@ -475,9 +584,11 @@ the pane itself stays `position: fixed` and doesn't move with either.
 
 {#if collapsed}
   <button
+    bind:this={pillEl}
     type="button"
     class={miniBase({ class: minimizedClass })}
-    onclick={() => (collapsed = false)}
+    data-draggable-pane-pill={uid}
+    onclick={() => setCollapsed(false)}
     aria-label={`Expand ${minimizedTitle ?? title ?? 'panel'}`}
   >
     <Icon name="open_in_full" size="sm" class={miniIcon()} />
@@ -487,7 +598,15 @@ the pane itself stays `position: fixed` and doesn't move with either.
   <div
     bind:this={panelEl}
     class={base({ class: className })}
-    {style}
+    data-draggable-pane={uid}
+    style:left={px(x)}
+    style:top={px(y)}
+    style:width={px(width)}
+    style:height={px(height)}
+    style:min-width={px(minWidth, resizable)}
+    style:min-height={px(minHeight, resizable)}
+    style:max-width={px(capWidth)}
+    style:max-height={px(capHeight)}
     role="group"
     aria-label={title}
     {@attach onClickOutside && clickOutside(onClickOutside)}
@@ -526,7 +645,7 @@ the pane itself stays `position: fixed` and doesn't move with either.
                 size="sm"
                 iconProps={{ name: 'collapse_all' }}
                 aria-label="Minimize"
-                onclick={() => (collapsed = true)}
+                onclick={() => setCollapsed(true)}
               />
             {/if}
             {#if onClose}

package/dist/components/date/DateField.svelte

@@ -114,7 +114,7 @@ Changing the visible month slides the grid with the M3 lateral transition (see c
     <DatePicker.Content sideOffset={4} align="start">
       {#snippet child({ wrapperProps, props, open })}
         <div {...wrapperProps}>
-          <div {...props} {@attach presence(() => open, enterExit.scale)}>
+          <div {...props} class="z-layer-popup" {@attach presence(() => open, enterExit.scale)}>
             <DatePicker.Calendar class={calendar.surface()}>
               {#snippet children({ months, weekdays })}
                 <DatePicker.Header class={calendar.header()}>

package/dist/components/date/DateRangeField.svelte

@@ -123,7 +123,7 @@ Changing the visible month slides the grid with the M3 lateral transition (see c
     <DateRangePicker.Content sideOffset={4} align="start">
       {#snippet child({ wrapperProps, props, open })}
         <div {...wrapperProps}>
-          <div {...props} {@attach presence(() => open, enterExit.scale)}>
+          <div {...props} class="z-layer-popup" {@attach presence(() => open, enterExit.scale)}>
             <DateRangePicker.Calendar class={calendar.surface()}>
               {#snippet children({ months, weekdays })}
                 <DateRangePicker.Header class={calendar.header()}>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noxlovette/material",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "type": "module",
   "description": "A Material Design 3 component library for Svelte, built on Bits UI.",
   "keywords": [