@multiplatform.one/forms 7.4.1 → 7.6.0

package/src/FloatingPanel/index.native.tsx

@@ -30,10 +30,12 @@
  *   backdrop dismiss is armed only after Modal.onShow + a short delay.
  */
 
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
-  KeyboardAvoidingView,
+  Animated,
+  Easing,
   Modal,
+  PanResponder,
   Platform,
   Pressable,
   ScrollView as RNScrollView,
@@ -44,6 +46,7 @@ import {
 import { Surface, useResolvedKnobs } from "@multiplatform.one/theme";
 import { View, YStack } from "tamagui";
 import { t } from "../shared/t";
+import { useKeyboardInset } from "../shared/useKeyboardInset";
 import type { FloatingPanelProps } from "./index";
 
 // Re-export the hook + constants so Select / Combobox / external consumers
@@ -68,6 +71,17 @@ const sheetMaxHeightRatio = 0.85;
 // Home-indicator / gesture-bar clearance (no react-native-safe-area-context
 // dependency in this package).
 const bottomInset = Platform.OS === "ios" ? 24 : 16;
+// Backdrop left visible above the sheet: the scrim has to stay tappable, and a
+// sheet flush with the status bar reads as a page, not a sheet.
+const backdropStrip = 48;
+// Never collapse to nothing on a landscape phone with the keyboard up.
+const minSheetHeight = 180;
+// Half-open detent for a sheet that owns a scrollport, as a fraction of its
+// full height. The web path hands Tamagui's Sheet [92, 50, 25]; on a phone one
+// intermediate stop is the only one worth having.
+const mediumDetent = 0.55;
+// Released more than this far below the smallest detent, the sheet dismisses.
+const dismissThreshold = 56;
 
 export function FloatingPanel({
   open,
@@ -82,27 +96,27 @@ export function FloatingPanel({
   scrollViewProps,
   triggerA11y,
   sheetFill,
+  openOn = "press",
 }: FloatingPanelProps) {
   const { knobProps } = useResolvedKnobs();
   const { height: windowHeight } = useWindowDimensions();
+  // MPO-64: the sheet must end ABOVE the keyboard, not run under it.
+  const keyboardInset = useKeyboardInset();
   const [backdropArmed, setBackdropArmed] = useState(false);
   const armTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
   const close = useCallback(() => onOpenChange(false), [onOpenChange]);
   const handleTriggerPress = useCallback(() => {
     if (!disabled) onOpenChange(!open);
   }, [disabled, onOpenChange, open]);
+  const handleTriggerLongPress = useCallback(() => {
+    if (!disabled) onOpenChange(true);
+  }, [disabled, onOpenChange]);
+  const isContextMenu = openOn === "contextmenu";
 
   const handleBackdropPress = useCallback(() => {
     if (backdropArmed) close();
   }, [backdropArmed, close]);
 
-  const handleModalShow = useCallback(() => {
-    if (armTimerRef.current) clearTimeout(armTimerRef.current);
-    // One frame + small delay so the opening tap cannot dismiss immediately.
-    armTimerRef.current = setTimeout(() => setBackdropArmed(true), 280);
-  }, []);
-
   useEffect(() => {
     if (!open) {
       setBackdropArmed(false);
@@ -118,7 +132,167 @@ export function FloatingPanel({
 
   const framePadding = contentPadding === "none" ? "$0" : knobProps.panelPadding.padding;
   const frameGap = contentPadding === "none" ? undefined : knobProps.gapLg.gap;
-  const maxHeight = Math.round(windowHeight * sheetMaxHeightRatio);
+  /*
+   * MPO-64. Two numbers, both of which have to know about the keyboard:
+   *
+   *   - the sheet may never be taller than the space ABOVE the keyboard, less
+   *     a strip of backdrop so it still reads as a sheet and the scrim stays
+   *     tappable. Without this the frame extends under the keyboard, the last
+   *     row is clipped mid-glyph, and the rounded top edge is drawn over the
+   *     autocomplete suggestion strip.
+   *   - the bottom padding is home-indicator clearance. The keyboard already
+   *     covers the home indicator, so keeping 24pt there just wastes a row.
+   */
+  const available = Math.max(0, windowHeight - keyboardInset);
+  const maxHeight = Math.max(
+    minSheetHeight,
+    Math.round(Math.min(windowHeight * sheetMaxHeightRatio, available - backdropStrip)),
+  );
+  const sheetBottomPadding = keyboardInset > 0 ? 8 : bottomInset;
+
+  /*
+   * MPO-68 — drag and detents.
+   *
+   * The web path hands Tamagui's Sheet `snapPoints={[92, 50, 25]}`. This
+   * native path is a hand-rolled RN Modal and never had any of it, so on
+   * device the sheet was open-or-closed and the grab handle was decoration.
+   *
+   * PanResponder, not react-native-gesture-handler: gesture-handler is not a
+   * dependency of this package, and inside a core RN `Modal` its gestures
+   * need their OWN GestureHandlerRootView within the modal to fire at all.
+   * Core PanResponder has neither problem.
+   *
+   * Geometry: `translateY` measures DOWN from fully-expanded, so 0 is the
+   * sheet at full height and `travel` is fully off-screen. A detent is a
+   * visible height; its resting translate is `travel - height`.
+   */
+  const [measuredHeight, setMeasuredHeight] = useState(0);
+  const travel = measuredHeight || maxHeight;
+  // A content-sized picker has exactly one useful resting height; only a sheet
+  // that owns a scrollport can meaningfully sit half-open.
+  const isSheet = !!scrollable || !!sheetFill;
+  const detents = useMemo(() => {
+    if (!isSheet) return [travel];
+    const points = [travel, Math.round(travel * mediumDetent)].filter(
+      (h) => h >= Math.min(minSheetHeight, travel),
+    );
+    return Array.from(new Set(points)).sort((a, b) => b - a);
+  }, [isSheet, travel]);
+
+  // Start OFF-SCREEN. `0` is "fully expanded", so a 0 default paints the
+  // sheet at rest for one frame, then onShow jumps it to `travel` and
+  // slides it up — Combobox/Select read as open → closed → open.
+  const translateY = useRef(new Animated.Value(10000)).current;
+  // The translate the sheet is settled at. Kept in a ref because the pan
+  // callbacks are created once and must not close over a stale value.
+  const restRef = useRef(10000);
+  const travelRef = useRef(travel);
+  const detentsRef = useRef(detents);
+  travelRef.current = travel;
+  detentsRef.current = detents;
+
+  useEffect(() => {
+    if (open) return;
+    // Park off-screen before the next present so the first painted frame of
+    // `visible={true}` is not the resting sheet (open → closed → open).
+    const parked = travelRef.current || 10000;
+    translateY.setValue(parked);
+    restRef.current = parked;
+  }, [open, translateY]);
+
+  const settleTo = useCallback(
+    (toValue: number, velocity = 0) => {
+      restRef.current = toValue;
+      Animated.spring(translateY, {
+        toValue,
+        velocity,
+        damping: 32,
+        stiffness: 320,
+        mass: 0.9,
+        overshootClamping: true,
+        useNativeDriver: true,
+      }).start();
+    },
+    [translateY],
+  );
+
+  const dismiss = useCallback(
+    (velocity = 0) => {
+      restRef.current = travelRef.current;
+      Animated.spring(translateY, {
+        toValue: travelRef.current,
+        velocity,
+        damping: 40,
+        stiffness: 400,
+        mass: 0.9,
+        overshootClamping: true,
+        useNativeDriver: true,
+      }).start(({ finished }) => {
+        if (finished) close();
+      });
+    },
+    [close, translateY],
+  );
+
+  const panResponder = useMemo(
+    () =>
+      PanResponder.create({
+        onStartShouldSetPanResponder: () => true,
+        onMoveShouldSetPanResponder: (_evt, g) => Math.abs(g.dy) > 2,
+        onPanResponderGrant: () => {
+          translateY.stopAnimation((value) => {
+            if (typeof value === "number" && Number.isFinite(value)) restRef.current = value;
+          });
+        },
+        onPanResponderMove: (_evt, g) => {
+          const next = restRef.current + g.dy;
+          // Rubber-band above fully-expanded: an upward drag past the top
+          // gives feedback but the sheet cannot leave its own frame.
+          translateY.setValue(next < 0 ? next / 3 : next);
+        },
+        onPanResponderRelease: (_evt, g) => {
+          const points = detentsRef.current;
+          const t = travelRef.current;
+          const current = Math.max(0, restRef.current + g.dy);
+          // Project where a flick would carry to, the way a scroll view does,
+          // so a fast short flick still changes detent.
+          const projected = current + g.vy * 120;
+          const smallestRest = t - points[points.length - 1];
+          if (projected > smallestRest + dismissThreshold || g.vy > 1.1) {
+            dismiss(g.vy);
+            return;
+          }
+          let best = points[0];
+          let bestDelta = Number.POSITIVE_INFINITY;
+          for (const height of points) {
+            const delta = Math.abs(projected - (t - height));
+            if (delta < bestDelta) {
+              bestDelta = delta;
+              best = height;
+            }
+          }
+          settleTo(t - best, g.vy);
+        },
+        onPanResponderTerminate: () => settleTo(restRef.current),
+      }),
+    [dismiss, settleTo, translateY],
+  );
+
+  const handleModalShow = useCallback(() => {
+    if (armTimerRef.current) clearTimeout(armTimerRef.current);
+    // One frame + small delay so the opening tap cannot dismiss immediately.
+    armTimerRef.current = setTimeout(() => setBackdropArmed(true), 280);
+    // MPO-62: the modal itself fades (so the backdrop dims IN PLACE) and only
+    // the sheet slides, on this transform.
+    translateY.setValue(travelRef.current);
+    restRef.current = 0;
+    Animated.timing(translateY, {
+      toValue: 0,
+      duration: 280,
+      easing: Easing.out(Easing.cubic),
+      useNativeDriver: true,
+    }).start();
+  }, [translateY]);
 
   const content = scrollable ? (
     <RNScrollView
@@ -138,7 +312,9 @@ export function FloatingPanel({
     <>
       <RNView style={{ flexDirection: "row", alignItems: "center", width: "100%" }}>
         <Pressable
-          onPress={handleTriggerPress}
+          {...(isContextMenu
+            ? { onLongPress: handleTriggerLongPress, delayLongPress: 500 }
+            : { onPress: handleTriggerPress })}
           disabled={disabled}
           accessibilityRole="button"
           accessibilityState={{ disabled: !!disabled, expanded: !!open }}
@@ -167,15 +343,17 @@ export function FloatingPanel({
       <Modal
         visible={open}
         transparent
-        animationType="slide"
+        animationType="fade"
         statusBarTranslucent
         onRequestClose={close}
         onShow={handleModalShow}
       >
-        <KeyboardAvoidingView
-          style={{ flex: 1, justifyContent: "flex-end" }}
-          behavior={Platform.OS === "ios" ? "padding" : undefined}
-        >
+        {/*
+          A plain padded column, not KeyboardAvoidingView: inside a Modal the
+          latter pads the container while the sheet keeps its own fixed height,
+          so the sheet overflows off the TOP instead of shrinking (MPO-64).
+        */}
+        <RNView style={{ flex: 1, justifyContent: "flex-end", paddingBottom: keyboardInset }}>
           <Pressable
             style={StyleSheet.absoluteFill}
             onPress={handleBackdropPress}
@@ -189,40 +367,69 @@ export function FloatingPanel({
             Do NOT claim the responder on a wrapper here — that steals presses
             from option rows / calendar days and blocks commit.
           */}
-          <YStack
-            {...knobProps.elevatedSurface}
-            borderBottomLeftRadius={0}
-            borderBottomRightRadius={0}
-            maxHeight={maxHeight}
-            // sheetFill opens at full sheet height (flexShrink keeps the
-            // keyboard from pushing the top of the sheet off-screen).
-            {...(sheetFill ? { height: maxHeight, flexShrink: 1 } : undefined)}
-            paddingTop="$2"
-            paddingBottom={bottomInset}
-            // VoiceOver escape gesture (two-finger Z) dismisses the sheet.
-            onAccessibilityEscape={close}
+          <Animated.View
+            onLayout={(e) => {
+              // Travel distance for a dismiss, and the basis for the detents.
+              // A content-sized picker is shorter than maxHeight, and sliding
+              // it by maxHeight would overshoot into a visible lag.
+              const h = Math.round(e.nativeEvent.layout.height);
+              if (h > 0 && h !== measuredHeight) setMeasuredHeight(h);
+            }}
+            style={{
+              // MPO-64: a flex child defaults to flexShrink 0, so without this
+              // the sheet cannot give way to the keyboard at all.
+              flexShrink: 1,
+              minHeight: 0,
+              maxHeight,
+              transform: [{ translateY }],
+            }}
           >
-            <View
-              alignSelf="center"
-              width={40}
-              height={4}
-              borderRadius={2}
-              backgroundColor="$color8"
-              marginBottom="$2"
-            />
             <YStack
-              padding={framePadding}
-              gap={frameGap}
-              flexShrink={1}
-              {...(sheetFill ? { flex: 1, minHeight: 0 } : undefined)}
+              {...knobProps.elevatedSurface}
+              borderBottomLeftRadius={0}
+              borderBottomRightRadius={0}
+              maxHeight={maxHeight}
+              // sheetFill opens at full sheet height (flexShrink keeps the
+              // keyboard from pushing the top of the sheet off-screen).
+              {...(sheetFill ? { height: maxHeight, flexShrink: 1 } : undefined)}
+              paddingTop="$2"
+              paddingBottom={sheetBottomPadding}
+              // VoiceOver escape gesture (two-finger Z) dismisses the sheet.
+              onAccessibilityEscape={close}
             >
-              <Surface size="md">
-                {header}
-                {content}
-              </Surface>
+              {/*
+                The grab ZONE, not just the 4pt pill: a 4pt tall target is
+                unhittable. The gesture lives here rather than on the whole
+                sheet so it never fights the ScrollView inside it, which is the
+                same division iOS uses.
+              */}
+              <RNView
+                {...panResponder.panHandlers}
+                accessibilityRole="adjustable"
+                accessibilityLabel={t("Drag to resize")}
+                style={{
+                  alignSelf: "stretch",
+                  alignItems: "center",
+                  paddingTop: 4,
+                  paddingBottom: 12,
+                }}
+              >
+                <View width={40} height={4} borderRadius={2} backgroundColor="$color8" />
+              </RNView>
+              <YStack
+                padding={framePadding}
+                gap={frameGap}
+                flexShrink={1}
+                {...(sheetFill ? { flex: 1, minHeight: 0 } : undefined)}
+              >
+                <Surface size="md">
+                  {header}
+                  {content}
+                </Surface>
+              </YStack>
             </YStack>
-          </YStack>
-        </KeyboardAvoidingView>
+          </Animated.View>
+        </RNView>
       </Modal>
     </>
   );

package/src/FloatingPanel/index.tsx

@@ -1,7 +1,7 @@
 import type { ReactNode, UIEvent } from "react";
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 import {
-  OVERLAY_ANCHOR_GAP,
+  OVERLAY_ATTACH_GAP,
   OVERLAY_BREAKPOINT,
   useResolvedKnobs,
   wasKeyboardFocus,
@@ -13,6 +13,7 @@ import { ScrollArrow } from "../shared/floatingList";
 import { useReturnFocusOnClose, useSheetModalFocus } from "../shared/focusManagement";
 import { useSheetEscapeDismiss } from "../shared/useSheetEscapeDismiss";
 import { useFloatingPanel, panelTransition, panelViewportPadding } from "./useFloatingPanel";
+import type { PanelWidthMode } from "./useFloatingPanel";
 import { zIndex } from "../shared/zIndex";
 
 // Re-export hook for Select / Combobox / external consumers
@@ -22,8 +23,14 @@ export {
   panelGrowDuration,
   panelTransition,
   panelViewportPadding,
+  panelAnchorOffset,
+  resolvePanelWidthMode,
+} from "./useFloatingPanel";
+export type {
+  PanelWidthMode,
+  UseFloatingPanelOptions,
+  UseFloatingPanelReturn,
 } from "./useFloatingPanel";
-export type { UseFloatingPanelOptions, UseFloatingPanelReturn } from "./useFloatingPanel";
 
 // ── Types ─────────────────────────────────────────────────────
 
@@ -39,6 +46,15 @@ export interface FloatingPanelProps {
    */
   triggerEnd?: ReactNode;
   children: ReactNode;
+  /**
+   * Wrap children in Sheet.ScrollView / RN ScrollView. For list overflow
+   * (Select / Combobox option lists), not gesture editors (ColorPicker,
+   * DatePicker, TimePicker, DatetimePicker, maps, signature). Gesture
+   * surfaces must not sit in a scrollport (LC-83): a hue, date-wheel, map,
+   * or signature drag otherwise scrolls the sheet instead of driving the
+   * control. If a picker is taller than the sheet it overflows — acceptable;
+   * overflow/scroll is for non-interactive lists.
+   */
   scrollable?: boolean;
   disabled?: boolean;
   /**
@@ -56,9 +72,17 @@ export interface FloatingPanelProps {
    */
   sizing?: "grow" | "fill";
   /**
-   * When true, the floating panel width is based on its content rather than
-   * matching the trigger element width. Useful for pickers like Calendar
-   * and ColorPicker that have fixed-width content.
+   * How the panel's width relates to the trigger it opened from (MPO-38).
+   * `"fit-content"` ignores the trigger, `"match-trigger"` is the trigger's
+   * width exactly, `"at-least-trigger"` (default) is max(trigger, content).
+   * A panel narrower than the control you clicked is not reachable, so
+   * anything opened from a field-shaped trigger takes the floor.
+   */
+  widthMode?: PanelWidthMode;
+  /**
+   * @deprecated Pass `widthMode` instead — the boolean cannot express
+   * `"match-trigger"`. `true` → `"fit-content"`, `false`/undefined →
+   * `"at-least-trigger"`. An explicit `widthMode` always wins.
    */
   fitContent?: boolean;
   /**
@@ -96,6 +120,13 @@ export interface FloatingPanelProps {
    * the strings must live on the Pressable itself. Web ignores this.
    */
   triggerA11y?: { label?: string; value?: string; hint?: string };
+  /**
+   * How the trigger opens the panel. `"press"` (default) is click/tap.
+   * `"contextmenu"` is the ContextMenu gesture: web `contextmenu` (right-click
+   * / Shift+F10), native long-press. Primary click does not open. Same overlay
+   * stack — not a second positioning engine.
+   */
+  openOn?: "press" | "contextmenu";
 }
 
 /** Inner stops a keyboard-open should land on. House Button is a
@@ -209,6 +240,7 @@ function FloatingPanelSheet({
   transition: transitionProp,
   header,
   scrollViewProps,
+  openOn = "press",
 }: FloatingPanelProps) {
   const { knobProps } = useResolvedKnobs();
   // LC-24 / A-ENTEREXIT: honor animation=none (undefined) — do not hardcode "medium".
@@ -252,8 +284,16 @@ function FloatingPanelSheet({
   // its overlay covers the trigger and the toggle could only ever have run
   // with `open === false`.
   const openFromTrigger = () => handleOpenChange(true);
+  const isContextMenu = openOn === "contextmenu";
   const triggerActivation = isWeb
-    ? ({ onClickCapture: openFromTrigger } as Record<string, unknown>)
+    ? isContextMenu
+      ? ({
+          onContextMenu: (event: { preventDefault: () => void }) => {
+            event.preventDefault();
+            openFromTrigger();
+          },
+        } as Record<string, unknown>)
+      : ({ onClickCapture: openFromTrigger } as Record<string, unknown>)
     : undefined;
 
   return (
@@ -262,7 +302,7 @@ function FloatingPanelSheet({
         <View
           flex={1}
           minWidth={0}
-          onPress={openFromTrigger}
+          {...(isContextMenu ? undefined : { onPress: openFromTrigger })}
           cursor={disabled ? "not-allowed" : "pointer"}
           opacity={disabled ? 0.5 : 1}
           {...triggerActivation}
@@ -325,8 +365,10 @@ function FloatingPanelWeb({
   children,
   disabled,
   sizing = "grow",
+  widthMode,
   fitContent,
   contentPadding = "default",
+  openOn = "press",
 }: FloatingPanelProps) {
   const isFill = sizing === "fill";
   const overlayStyleRef = useRef<{ top: number; maxHeight: number } | null>(null);
@@ -346,6 +388,7 @@ function FloatingPanelWeb({
     disabled,
     repositionRef: repositionFnRef,
     wheelGrowRef: isFill ? undefined : grownRef,
+    widthMode,
     fitContent,
     onBeforeOpen: () => {
       overlayStyleRef.current = null;
@@ -391,8 +434,11 @@ function FloatingPanelWeb({
     const liveTransition = panel.knobProps.transition ? panelTransition : "none";
 
     const isDropup = panel.placement.startsWith("top");
-    const gap = OVERLAY_ANCHOR_GAP;
-    // Anchor beside the trigger (Radix / Apple / Fluent), never covering it.
+    // Cover ruling (MPO-38): the panel ATTACHES to the trigger it was opened
+    // from. `OVERLAY_ATTACH_GAP` is 0, so the panel's top edge coincides with
+    // the trigger's bottom edge (and its bottom with the trigger's top when
+    // dropping up) instead of floating 4px clear of it.
+    const gap = OVERLAY_ATTACH_GAP;
     const belowTop = triggerBounds.bottom + gap;
     const aboveBottom = triggerBounds.top - gap;
 
@@ -507,7 +553,11 @@ function FloatingPanelWeb({
 
   repositionFnRef.current = repositionOverlay;
 
-  const click = useClick(panel.context, { event: "mousedown" });
+  const isContextMenu = openOn === "contextmenu";
+  const click = useClick(panel.context, {
+    event: "mousedown",
+    enabled: !isContextMenu,
+  });
   const dismiss = useDismiss(panel.context, {
     // Use 'click' instead of default 'pointerdown' so scrolling to the bottom
     // (e.g. via wheel/trackpad or scroll arrow hover) doesn't trigger outside-press.
@@ -557,6 +607,18 @@ function FloatingPanelWeb({
   // animation=none → no CSS tween (same contract as knobProps.transition === undefined)
   const webTransition = panel.knobProps.transition ? panelTransition : "none";
 
+  // `elevatedSurface` carries a web-only `style: { boxShadow }` (MPO-69,
+  // d326cc0c2). Two `style` props on one element do NOT merge — the later
+  // spread replaces the earlier — so spreading the complete fragment after the
+  // positioning style silently dropped `position: fixed`, `top`, `left`,
+  // `zIndex` and `overflow`, and every web FloatingPanel rendered in normal
+  // flow, pushing the page down instead of floating over it. Measured on
+  // origin/main 048289071: DatePicker's panel sat at trigger.bottom + 5.39 (the
+  // field container's flex gap), not the contract's 0.
+  // The complete fragment still goes on the element (AGENTS.md) — its style is
+  // folded into the positioning style rather than competing with it.
+  const { style: elevatedSurfaceStyle, ...elevatedSurfaceProps } = panel.knobProps.elevatedSurface;
+
   // Same slot problem as the sheet branch, but only half of it lands here. The
   // POINTER path survives, because `useClick(..., { event: "mousedown" })`
   // listens on mousedown and Tamagui only stops the click. The KEYBOARD path
@@ -572,12 +634,21 @@ function FloatingPanelWeb({
   // count, `element.click()` and native keyboard activation carry 0.
   const openFromSynthesizedClick = useCallback(
     (event: { detail: number }) => {
-      if (disabled || event.detail !== 0) return;
+      if (disabled || isContextMenu || event.detail !== 0) return;
       // detail 0 is keyboard/programmatic activation (LC-50). Count it as
       // keyboard-origin so the first inner control rings (LC-71).
       keyboardOpenRef.current = true;
       onOpenChange(true);
     },
+    [disabled, isContextMenu, onOpenChange],
+  );
+
+  const openFromContextMenu = useCallback(
+    (event: { preventDefault: () => void }) => {
+      event.preventDefault();
+      if (disabled) return;
+      onOpenChange(true);
+    },
     [disabled, onOpenChange],
   );
 
@@ -587,9 +658,17 @@ function FloatingPanelWeb({
         {...getReferenceProps({
           ref: panel.setReferenceRef,
           onClickCapture: openFromSynthesizedClick,
+          ...(isContextMenu ? { onContextMenu: openFromContextMenu } : {}),
         })}
         cursor={disabled ? "not-allowed" : "pointer"}
         opacity={disabled ? 0.5 : 1}
+        // The cover contract is stated as a relation between the panel's top
+        // edge and THIS element's bottom edge — the box floating-ui anchors
+        // to, which is the whole trigger, not whatever glyph inside it was
+        // clicked. Marking it keeps the measurement unambiguous (a ColorPicker
+        // read from its swatch measures the swatch's inset, not the gap).
+        // Same idiom TreeSelect already uses for `data-fp-panel`.
+        data-fp-reference=""
       >
         {trigger}
       </View>
@@ -599,6 +678,7 @@ function FloatingPanelWeb({
           {...getFloatingProps({
             ref: panel.refs.setFloating,
             style: {
+              ...elevatedSurfaceStyle,
               position: panel.strategy,
               top: overlayStyleRef.current?.top ?? panel.y ?? 0,
               left: panel.x ?? 0,
@@ -615,9 +695,10 @@ function FloatingPanelWeb({
             onScroll: handleScroll,
           })}
           data-testid="floating-panel-viewport"
+          data-fp-panel=""
           {...panelChromeFocus}
           pointerEvents={panel.visible ? "auto" : "none"}
-          {...panel.knobProps.elevatedSurface}
+          {...elevatedSurfaceProps}
           // Complete elevatedSurface fragment above is the ONLY surface source
           // (SF-OVERLAY "including border and elevation", Round 2 docket).
           // The one layered exception is anatomy, not surface: the dropdown

package/src/FloatingPanel/panelWidthContract.spec.ts

@@ -0,0 +1,58 @@
+/**
+ * MPO-38 AC: no FloatingPanel consumer renders a panel narrower than its
+ * trigger.
+ *
+ * The runtime half is covered in `useFloatingPanel.spec.tsx`. This is the
+ * source half, and it exists because the defect it guards is invisible at
+ * runtime unless someone opens that one picker at that one field width:
+ * DatePicker measured 262px of calendar under a 289px trigger purely because
+ * the call site said `fitContent`.
+ *
+ * A FIELD-shaped trigger (a control the user reads a value out of) takes
+ * `at-least-trigger`. A BUTTON-shaped trigger — an icon, a toolbar chip —
+ * legitimately keeps `fit-content`, because matching a 32px button would be
+ * absurd; those are listed explicitly so the exemption is a decision rather
+ * than an oversight.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const fieldsDir = resolve(dirname(fileURLToPath(import.meta.url)), "..", "fields");
+
+/** Pickers whose trigger is a form FIELD: the panel may never be narrower. */
+const fieldShapedPickers = [
+  "DatePicker/parts.tsx",
+  "DatePicker/DatetimePicker.tsx",
+  "TimePicker/index.tsx",
+  "ColorPicker/parts.tsx",
+  "Icon/index.tsx",
+];
+
+/** Panels opened from an icon/button trigger, where fit-content is correct. */
+const buttonShapedPickers = ["Geolocation/index.tsx"];
+
+function read(relative: string): string {
+  return readFileSync(resolve(fieldsDir, relative), "utf8");
+}
+
+describe("FloatingPanel width contract (MPO-38)", () => {
+  it.each(fieldShapedPickers)("%s declares at-least-trigger", (relative) => {
+    const source = read(relative);
+    expect(source).toContain('widthMode="at-least-trigger"');
+  });
+
+  it.each(fieldShapedPickers)("%s no longer passes the fitContent boolean", (relative) => {
+    const source = read(relative);
+    expect(source).not.toMatch(/^\s*fitContent\s*$/m);
+    expect(source).not.toMatch(/fitContent=\{?true/);
+  });
+
+  it.each(buttonShapedPickers)("%s keeps fit-content deliberately", (relative) => {
+    const source = read(relative);
+    // Asserted, not merely tolerated: if this stops being true the exemption
+    // list is stale and someone must re-judge it rather than delete a line.
+    expect(source).toMatch(/fitContent/);
+  });
+});