fix(core): a BottomSheet touch drag's close keeps its speed, and its scrim fades with it

.changeset/bottom-sheet-drag-close.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] BottomSheet: a sheet a touch drag closes leaves on its close spring, starting at the speed of the drag, and its scrim fades out with it on one clock, at the theme's tempo. A BottomSheetSwitcher flow's scrim does too. A mouse or pen drag is unchanged.
+
+@vjeux

.changeset/motion-settle-clock.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: the motion foundation's `resolveSettleMs` gives a spring role's settling time at the theme's tempo, so a CSS part that plays with the spring can start and land with it. Not exported from the package entry point.
+
+@vjeux

docs/specs/AST-094-touch-presentations/motion-roles.md

@@ -21,6 +21,7 @@ The owner's goal: "The main goals are consistent timings and well-coordinated pi
 | `springs.menuOpen`              | spring   | response 0.32 s, damping ratio 0.8                              | `spec:AST-094` FR4      |
 | `springs.quickChange`           | spring   | duration 0.5 s, bounce 0.15                                     | `spec:AST-094` FR4      |
 | `springs.settle`                | spring   | duration 0.5 s, bounce 0                                        | `spec:AST-094` FR4      |
+| `springs.sheetDismissSwipe`     | spring   | response 0.3441442326 s, damping ratio 0.8                      | `component:BottomSheet` |
 | `springs.sliderDrop`            | spring   | response 0.5 s, damping ratio 0.7                               | `component:Slider`      |
 | `springs.sliderLift`            | spring   | response 0.215 s, damping ratio 0.6                             | `component:Slider`      |
 | `springs.sliderRelease`         | spring   | response 0.4 s, damping ratio 1                                 | `component:Slider`      |

packages/core/src/BottomSheet/BottomSheet.tsx

@@ -305,6 +305,37 @@ function scrimOpacityForView(view: BottomSheetStackView): '0' | '1' {
   return view.isStacked && !view.ownsScrim ? '0' : '1';
 }
 
+/**
+ * Writes the fade a touch drag's close paces on `dialog`'s scrim, or clears
+ * it when `ms` is null. `written` keeps the value the host wrote, so a clear
+ * removes only that value.
+ */
+function writeScrimFadeDuration(
+  dialog: HTMLDialogElement | null,
+  ms: number | null,
+  written: {current: string | null},
+): void {
+  if (dialog == null) {
+    return;
+  }
+  const current = dialog.style.getPropertyValue('--_sheet-scrim-duration');
+  if (ms == null) {
+    // Remove only the value this host wrote. A stack's 0s pin written since
+    // then stays.
+    if (written.current != null && current === written.current) {
+      dialog.style.removeProperty('--_sheet-scrim-duration');
+    }
+    written.current = null;
+    return;
+  }
+  // A stack's 0s pin hands the scrim over with no fade; it stays.
+  if (current === '0s') {
+    return;
+  }
+  written.current = `${ms}ms`;
+  dialog.style.setProperty('--_sheet-scrim-duration', written.current);
+}
+
 interface BottomSheetSharedProps extends BaseProps<HTMLDivElement> {
   /** Ref forwarded to the visual sheet panel <div>. */
   ref?: React.Ref<HTMLDivElement>;
@@ -544,6 +575,18 @@ function StandaloneBottomSheet({
       String(opacity),
     );
   }, []);
+  // The fade duration a touch drag's close wrote, until that close ends.
+  const scrimFadeRef = useRef<string | null>(null);
+  const handleScrimFadeDuration = useCallback(
+    (panel: HTMLElement, ms: number | null) => {
+      const view = stackViewRef.current;
+      if (view.isStacked && !view.ownsScrim) {
+        return;
+      }
+      writeScrimFadeDuration(panel.closest('dialog'), ms, scrimFadeRef);
+    },
+    [],
+  );
 
   // A sheet joins the registry for as long as it is presented. For a modal
   // sheet the registry shows the dialog (in open order, repairing same-commit
@@ -946,6 +989,7 @@ function StandaloneBottomSheet({
         xstyle={xstyle}
         onDismiss={dismissOnLightInteraction}
         onScrimOpacity={handleScrimOpacity}
+        onScrimFadeDuration={handleScrimFadeDuration}
         onElementChange={handlePanelElementChange}
         onMotionStart={handleMotionStart}
         onMotionComplete={handleMotionComplete}>
@@ -1095,6 +1139,16 @@ function SwitcherBottomSheetItem({
     },
     [hasValidSheetId, onSheetScrimOpacityChange, sheetId],
   );
+  // The fade a touch drag's close wrote on this step's dialog, until that
+  // close ends. The step a drag closes becomes the flow's retained step, so
+  // its backdrop is the flow's scrim.
+  const scrimFadeRef = useRef<string | null>(null);
+  const handleScrimFadeDuration = useCallback(
+    (panel: HTMLElement, ms: number | null) => {
+      writeScrimFadeDuration(panel.closest('dialog'), ms, scrimFadeRef);
+    },
+    [],
+  );
 
   useLayoutEffect(() => {
     if (!hasValidSheetId) {
@@ -1297,6 +1351,7 @@ function SwitcherBottomSheetItem({
           xstyle={xstyle}
           onDismiss={dismissOnSwipe}
           onScrimOpacity={handleScrimOpacity}
+          onScrimFadeDuration={handleScrimFadeDuration}
           onElementChange={handlePanelElementChange}
           onMotionStart={handleMotionStart}
           onMotionComplete={handleMotionComplete}>