@multiplatform.one/forms 7.72.0 → 7.73.0

package/src/FloatingPanel/index.tsx

@@ -15,6 +15,7 @@ import {
   OVERLAY_ATTACH_GAP,
   OVERLAY_BREAKPOINT,
   Surface,
+  SurfaceContext,
   useResolvedKnobs,
   wasKeyboardFocus,
   ensureKeyboardModalityTracking,
@@ -40,6 +41,14 @@ import { OverlayStackProvider, useInsideOverlay, useOverlayZIndex } from "../sha
 import { resolveCompactFace, type CompactFace } from "./compactFace";
 import { isNestedPanelAction, type PanelActionEvent } from "./nestedAction";
 import { PanelPortal } from "./PanelPortal";
+import {
+  echoHeaderBox,
+  PanelIconEchoBoxContext,
+  sameEchoBox,
+  type PanelIconEchoBox,
+} from "./echoContext";
+import { iconEchoElement, iconEchoOverlays, type IconEcho } from "./iconEcho";
+import { groupSurfaceOf, paintedTriggerBox } from "./paintedBox";
 import {
   contextMenuPoint,
   placeOverTrigger,
@@ -92,6 +101,15 @@ export interface FloatingPanelProps {
    * instead of handing it to a sheet, the way an iOS menu grows out of it.
    */
   coverAlign?: "start" | "auto";
+  /**
+   * An icon-only trigger's covering panel draws the pressed button again in
+   * its own spot as an X, same size and plate, the way iOS morphs a + into an
+   * X (LC-112, FZ-8480 Round 37). `"close"` lays the X over the content's
+   * header row; `"menu"` gives it its own band above the rows. It closes the
+   * panel and reads "Close". The panel never slides off the button: it opens
+   * down from the button's top edge, or up from its bottom edge.
+   */
+  iconEcho?: IconEcho;
   /**
    * Optional control rendered beside the trigger but OUTSIDE the native press
    * capture (e.g. DatePicker/ColorPicker clear). On native the trigger subtree
@@ -519,6 +537,103 @@ export function placeEchoOverTrigger(
   }
 }
 
+/**
+ * The band an icon trigger's echo rides (LC-112, FZ-8480): as tall as the
+ * trigger, sticky on the panel's top edge (or its bottom edge when the panel
+ * opened upward), filled with the panel's surface so scrolled rows pass under
+ * it. It comes last in the document, so a keyboard open lands on the panel's
+ * content and the echo is the last tab stop; CSS order draws it first.
+ */
+function IconEchoRow({ children }: { children: ReactNode }) {
+  return (
+    <View
+      data-fp-icon-echo=""
+      flexShrink={0}
+      alignSelf="stretch"
+      pointerEvents="box-none"
+      style={{ order: -1, position: "sticky", zIndex: 1 }}
+    >
+      <View data-fp-icon-echo-box="" alignItems="flex-start" justifyContent="flex-start">
+        {children}
+      </View>
+    </View>
+  );
+}
+
+/**
+ * Lay the icon echo on the trigger's measured box: the band is the trigger's
+ * height on the edge the panel shares with it, and the box sits `offset` in
+ * from the panel's start edge, pulled back over the frame's border so the
+ * button lands exactly where the trigger is. An overlaid echo (an X) takes no
+ * height of its own and lets the content show beside it.
+ */
+function placeIconEcho(
+  panelElement: HTMLElement,
+  {
+    offset,
+    width,
+    height,
+    up,
+    overlay,
+    group = null,
+  }: {
+    offset: number;
+    width: number;
+    height: number;
+    up: boolean;
+    overlay: boolean;
+    /**
+     * The shared plate a grouped trigger sits on: the band covers all of it,
+     * and only the pressed trigger shows, at its own spot in the plate.
+     */
+    group?: { top: number; height: number } | null;
+  },
+) {
+  const row = panelElement.querySelector<HTMLElement>("[data-fp-icon-echo]");
+  const box = row?.querySelector<HTMLElement>("[data-fp-icon-echo-box]");
+  if (!row || !box) return;
+  const frame = getComputedStyle(panelElement);
+  const border = (side: "Top" | "Bottom" | "Left" | "Right") =>
+    parseFloat(frame[`border${side}Width`] || "0") || 0;
+  const rtl = panelElement.dir === "rtl";
+  row.style.order = up ? "1" : "-1";
+  row.style.height = `${height}px`;
+  row.style.backgroundColor = overlay ? "transparent" : frame.backgroundColor;
+  if (up) {
+    row.style.top = "";
+    row.style.marginTop = "";
+    row.style.marginBottom = `${-border("Bottom")}px`;
+    row.style.bottom = row.style.marginBottom;
+  } else {
+    row.style.bottom = "";
+    row.style.marginTop = `${-border("Top")}px`;
+    row.style.marginBottom = overlay ? `${-(height - border("Top"))}px` : "";
+    row.style.top = row.style.marginTop;
+  }
+  row.setAttribute("data-fp-icon-echo", overlay ? "overlay" : "band");
+  if (group) {
+    row.style.height = `${group.height}px`;
+    if (!up && overlay) row.style.marginBottom = `${-(group.height - border("Top"))}px`;
+  }
+  row.style.marginLeft = `${-border("Left")}px`;
+  row.style.marginRight = `${-border("Right")}px`;
+  box.style.width = `${width}px`;
+  box.style.height = `${height}px`;
+  box.style.marginLeft = rtl ? "" : `${offset}px`;
+  box.style.marginRight = rtl ? `${offset}px` : "";
+  box.style.alignSelf = "flex-start";
+  box.style.marginTop = group ? `${group.top}px` : "";
+  box.style.position = "relative";
+  box.style.zIndex = "1";
+}
+
+/** The box that lays an element out, past any `display: contents` wrappers. */
+function layoutParentOf(element: HTMLElement | null): HTMLElement | null {
+  let parent = element?.parentElement ?? null;
+  while (parent && getComputedStyle(parent).display === "contents") parent = parent.parentElement;
+  return parent;
+}
+
 // ── FloatingPanel ─────────────────────────────────────────────
 
 // Canonical float↔sheet pivot (theme `layoutBreakpoints.medium` = Tamagui
@@ -767,6 +882,7 @@ function FloatingPanelWeb({
   cover = true,
   triggerEcho = true,
   coverAlign = "start",
+  iconEcho,
   triggerRow,
   anchorRect,
   clampCollisions = false,
@@ -776,6 +892,13 @@ function FloatingPanelWeb({
   const [collisionSheet, setCollisionSheet] = useState(false);
   const isFill = sizing === "fill";
   const isContextMenu = openOn === "contextmenu";
+  // A context menu anchored on its trigger (a bar button's long-press menu)
+  // covers the trigger like any other menu; only a free one opens at the point.
+  const pointMenu = isContextMenu && sheetProps.anchorMode !== "cover-trigger";
+  const showIconEcho = cover && !pointMenu && iconEcho != null;
+  const triggerSurface = SurfaceContext.useStyledContext();
+  const iconEchoUpRef = useRef(false);
+  const [echoBox, setEchoBox] = useState<PanelIconEchoBox | null>(null);
   const overlayStyleRef = useRef<{ top: number; left?: number; maxHeight: number } | null>(null);
   const pinnedTopRef = useRef(0);
   const pinnedHeightRef = useRef(0);
@@ -810,10 +933,10 @@ function FloatingPanelWeb({
     wheelGrowRef: isFill ? undefined : grownRef,
     widthMode: widthMode ?? (isContextMenu && fitContent === undefined ? "fit-content" : undefined),
     fitContent,
-    freeOverlay: isContextMenu,
+    freeOverlay: pointMenu,
     cover,
     panelWidth,
-    echo: cover && triggerEcho && !isContextMenu,
+    echo: cover && triggerEcho && !pointMenu,
     onBeforeOpen: resetPosition,
   });
 
@@ -854,7 +977,7 @@ function FloatingPanelWeb({
       dropdownElement.scrollTop = 0;
     }
 
-    const point = isContextMenu
+    const point = pointMenu
       ? (anchorPointRef.current ?? referenceCornerPoint(trig, isRtl()))
       : null;
     const measured = anchorRect
@@ -887,6 +1010,12 @@ function FloatingPanelWeb({
         (viewport?.width ?? (document.documentElement.clientWidth || window.innerWidth));
       const viewportBottom = viewportTop + (viewport?.height ?? window.innerHeight);
       dropdownElement.style.left = `${viewportLeft - containingBlock.left}px`;
+      // LC-112 (FZ-8480 Round 37): a grouped icon trigger's surface is the
+      // group's plate, so the panel covers the whole plate; only the pressed
+      // trigger shows, as its X.
+      const groupSurface = showIconEcho ? groupSurfaceOf(trig) : null;
+      const groupBox = groupSurface?.getBoundingClientRect() ?? null;
+      if (showIconEcho) dropdownElement.style.minWidth = groupBox ? `${groupBox.width}px` : "";
       const layoutStyle = getComputedStyle(dropdownElement);
       const scale =
         layoutStyle.transform &&
@@ -955,7 +1084,38 @@ function FloatingPanelWeb({
         : totalContentHeight;
       let placedTop = measured.top;
       let placedLeft = left;
-      if (
+      let placedMaxHeight: number | null = null;
+      iconEchoUpRef.current = false;
+      if (showIconEcho && measured.width > 0 && measured.height > 0) {
+        // LC-112 (FZ-8480): the button is drawn again in its own spot, so the
+        // panel stays on it: down from its top edge, or up from its bottom.
+        // It covers the button's plate and press box where they reach past it.
+        const painted = groupBox ?? paintedTriggerBox(trig, measured);
+        const placed = placeOverTrigger({
+          trigger: {
+            x: painted.left,
+            y: groupBox ? groupBox.top : measured.top,
+            width: painted.right - painted.left,
+            height: groupBox ? groupBox.height : measured.height,
+          },
+          width,
+          height: totalContentHeight,
+          bounds: {
+            top: viewportTop + panelViewportPadding,
+            left: viewportLeft + panelViewportPadding,
+            right: viewportRight - panelViewportPadding,
+            bottom: viewportBottom - panelViewportPadding,
+          },
+          rtl,
+          align: coverAlign,
+          pinned: true,
+        });
+        placedTop = placed.top;
+        if (!slides) placedLeft = placed.left;
+        alignEnd = placed.end;
+        placedMaxHeight = placed.maxHeight;
+        iconEchoUpRef.current = placed.up;
+      } else if (
         measured.width > 0 &&
         measured.height > 0 &&
         ((!slides &&
@@ -996,6 +1156,36 @@ function FloatingPanelWeb({
         alignEnd = placed.end;
       }
       coverAlignEndRef.current = alignEnd;
+      const echoStart = echoOffset({
+        triggerLeft: measured.left,
+        triggerRight: measured.right,
+        panelLeft: placedLeft,
+        panelWidth: width,
+        rtl,
+      });
+      const echoOverlays = iconEcho != null && iconEchoOverlays(iconEcho, iconEchoUpRef.current);
+      const nextEchoBox =
+        showIconEcho && echoOverlays
+          ? echoHeaderBox({
+              offset: echoStart,
+              width: measured.width,
+              height: measured.height,
+              panelWidth: width,
+              rtl,
+            })
+          : null;
+      setEchoBox((previous) => (sameEchoBox(previous, nextEchoBox) ? previous : nextEchoBox));
+      placeIconEcho(dropdownElement, {
+        offset: echoStart,
+        width: measured.width,
+        height: measured.height,
+        up: iconEchoUpRef.current,
+        overlay: echoOverlays,
+        group:
+          groupSurface && groupBox
+            ? { top: measured.top - groupBox.top, height: groupBox.height }
+            : null,
+      });
       placeEchoOverTrigger(
         dropdownElement,
         {
@@ -1009,12 +1199,13 @@ function FloatingPanelWeb({
       );
       const top = placedTop - containingBlock.top;
       const cssLeft = placedLeft - containingBlock.left;
-      const maxHeight = Math.max(0, viewportBottom - panelViewportPadding - placedTop);
+      const maxHeight =
+        placedMaxHeight ?? Math.max(0, viewportBottom - panelViewportPadding - placedTop);
       dropdownElement.style.top = `${top}px`;
       dropdownElement.style.left = `${cssLeft}px`;
       dropdownElement.style.maxHeight = `${maxHeight}px`;
       dropdownElement.dir = rtl ? "rtl" : "ltr";
-      dropdownElement.style.transformOrigin = rtl !== alignEnd ? "top right" : "top left";
+      dropdownElement.style.transformOrigin = `${iconEchoUpRef.current ? "bottom" : "top"} ${rtl !== alignEnd ? "right" : "left"}`;
       dropdownElement.style.visibility = "visible";
       overlayStyleRef.current = { top, left: cssLeft, maxHeight };
       panel.initializingRef.current = false;
@@ -1174,6 +1365,8 @@ function FloatingPanelWeb({
   }, [
     isFill,
     isContextMenu,
+    pointMenu,
+    showIconEcho,
     cover,
     anchorRect,
     clampCollisions,
@@ -1243,7 +1436,7 @@ function FloatingPanelWeb({
     (event: UIEvent) => {
       const el = event.target as HTMLElement;
       panel.updateArrows(el);
-      if (isFill || (cover && !isContextMenu)) return;
+      if (isFill || (cover && !pointMenu)) return;
       if (panel.initializingRef.current) {
         lastScrollTopRef.current = el.scrollTop;
         return;
@@ -1267,7 +1460,7 @@ function FloatingPanelWeb({
         repositionFnRef.current?.();
       }
     },
-    [isFill, cover, isContextMenu, panel.updateArrows],
+    [isFill, cover, pointMenu, panel.updateArrows],
   );
 
   const webTransition = panel.panelTransition;
@@ -1354,6 +1547,24 @@ function FloatingPanelWeb({
     onClickCapture: openFromSynthesizedClick,
     ...(isContextMenu ? { onContextMenu: openFromContextMenu } : {}),
   });
+  // A content-sized trigger hugs its button instead of stretching across its
+  // parent's cross axis. In a row that centres its items (a bar's capsule) it
+  // keeps that centring, so an avatar sits on the row's line with its
+  // neighbours (FZ-8480 Round 37).
+  const contentSized = sheetProps.triggerSizing === "content";
+  const [hugSelf, setHugSelf] = useState<"flex-start" | undefined>(
+    contentSized ? "flex-start" : undefined,
+  );
+  useLayoutEffect(() => {
+    if (!contentSized) {
+      setHugSelf(undefined);
+      return;
+    }
+    const parent = layoutParentOf(panel.triggerRef.current);
+    const align = parent ? getComputedStyle(parent).alignItems : "stretch";
+    setHugSelf(align === "stretch" || align === "normal" ? "flex-start" : undefined);
+  }, [contentSized, panel.triggerRef]);
+
   // Guard the composed floating-ui openers, after hook handlers are merged.
   // Declining leaves each action's own events and focus defaults intact.
   for (const name of ["onMouseDown", "onClick", "onKeyDown", "onKeyUp"] as const) {
@@ -1371,7 +1582,7 @@ function FloatingPanelWeb({
     <>
       <View
         {...referenceProps}
-        alignSelf={sheetProps.triggerSizing === "content" ? "flex-start" : undefined}
+        alignSelf={hugSelf}
         cursor={disabled ? "not-allowed" : "pointer"}
         opacity={disabled ? 0.5 : 1}
         // The cover contract is stated as a relation between the panel's top
@@ -1417,7 +1628,7 @@ function FloatingPanelWeb({
                   scrollbarWidth: "none" as any,
                   zIndex: panelZIndex,
                   overflow: "auto",
-                  ...(cover && !isContextMenu ? { overflowX: "hidden" as const } : {}),
+                  ...(cover && !pointMenu ? { overflowX: "hidden" as const } : {}),
                   ...panel.floatingStyleRef.current,
                   ...(overlayStyleRef.current
                     ? { maxHeight: overlayStyleRef.current.maxHeight }
@@ -1429,10 +1640,12 @@ function FloatingPanelWeb({
                   transform: panel.visible ? "none" : "scale(0.96)",
                   transition: webTransition,
                   transformOrigin:
-                    cover && !isContextMenu
-                      ? isRtl(panel.triggerRef.current) !== coverAlignEndRef.current
-                        ? "top right"
-                        : "top left"
+                    cover && !pointMenu
+                      ? `${iconEchoUpRef.current ? "bottom" : "top"} ${
+                          isRtl(panel.triggerRef.current) !== coverAlignEndRef.current
+                            ? "right"
+                            : "left"
+                        }`
                       : panelTransformOrigin(
                           pointPlacementRef.current
                             ? `${pointPlacementRef.current.dropup ? "top" : "bottom"}-${pointPlacementRef.current.alignEnd ? "end" : "start"}`
@@ -1464,7 +1677,7 @@ function FloatingPanelWeb({
               paddingVertical={0}
               paddingBottom={panel.coverCornerInset || 0}
             >
-              {isContextMenu || !cover || !triggerEcho ? null : (
+              {pointMenu || !cover || !triggerEcho || showIconEcho ? null : (
                 <TriggerEchoRow
                   sourceRef={panel.triggerRef}
                   source={trigger}
@@ -1485,7 +1698,11 @@ function FloatingPanelWeb({
                 {...(contentPadding !== "none" ? panel.knobProps.panelPadding : undefined)}
                 {...(contentPadding !== "none" ? panel.knobProps.gapLg : undefined)}
               >
-                <OverlayStackProvider zIndex={panelZIndex}>{children}</OverlayStackProvider>
+                <OverlayStackProvider zIndex={panelZIndex}>
+                  <PanelIconEchoBoxContext.Provider value={echoBox}>
+                    {children}
+                  </PanelIconEchoBoxContext.Provider>
+                </OverlayStackProvider>
               </View>
               <ScrollArrow
                 direction="down"
@@ -1493,6 +1710,11 @@ function FloatingPanelWeb({
                 visible={panel.arrowDown}
                 arrowScrollDirRef={panel.arrowScrollDirRef}
               />
+              {showIconEcho && iconEcho ? (
+                <IconEchoRow>
+                  {iconEchoElement(trigger, iconEcho, () => onOpenChange(false), triggerSurface)}
+                </IconEchoRow>
+              ) : null}
             </YStack>
           </Theme>
         </PanelPortal>

package/src/FloatingPanel/paintedBox.spec.ts

@@ -0,0 +1,95 @@
+/**
+ * LC-112 (FZ-8480): a panel covering an icon trigger covers the button as it
+ * is drawn. The 1440 + hung 6px past its layout slot on its press slop, and
+ * the 390 + sat in a lone glass capsule 6px wider on each side; both left a
+ * sliver of the button showing beside the panel.
+ */
+import { afterEach, describe, expect, it } from "vitest";
+import { PAINTED_BOX_REACH, paintedTriggerBox } from "./paintedBox";
+
+type Rect = [left: number, top: number, width: number, height: number];
+
+function el(rect: Rect | null, children: HTMLElement[] = [], style = "") {
+  const node = document.createElement("div");
+  if (style) node.setAttribute("style", style);
+  for (const child of children) node.appendChild(child);
+  const [left, top, width, height] = rect ?? [0, 0, 0, 0];
+  node.getBoundingClientRect = () =>
+    ({
+      left,
+      top,
+      width,
+      height,
+      x: left,
+      y: top,
+      right: left + width,
+      bottom: top + height,
+      toJSON: () => ({}),
+    }) as DOMRect;
+  return node;
+}
+
+const box = ([left, top, width, height]: Rect) => ({
+  left,
+  top,
+  right: left + width,
+  bottom: top + height,
+});
+
+afterEach(() => {
+  document.body.replaceChildren();
+});
+
+describe("paintedTriggerBox (FZ-8480)", () => {
+  it("takes in a bare glyph's press box that hangs past its layout slot", () => {
+    const button = el([1302.5, 61, 40, 40]);
+    const reference = el([1302.5, 61, 34, 40], [el(null, [button], "display: contents")]);
+    document.body.appendChild(el([1302.5, 61, 34, 40], [reference]));
+    expect(paintedTriggerBox(reference, box([1302.5, 61, 34, 40]))).toEqual(
+      box([1302.5, 61, 40, 40]),
+    );
+  });
+
+  it("takes in a lone button's plate, ignoring the plate's absolute face", () => {
+    const reference = el([324, 61, 44, 44]);
+    const face = el([318, 61, 56, 44], [], "position: absolute");
+    const capsule = el([318, 61, 56, 44], [face, reference]);
+    const row = el([16, 61, 358, 44], [el([16, 61, 200, 44]), capsule]);
+    document.body.appendChild(row);
+    expect(paintedTriggerBox(reference, box([324, 61, 44, 44]))).toEqual(box([318, 61, 56, 44]));
+  });
+
+  it("stops at a wrapper shared with other content", () => {
+    const reference = el([290, 0, 44, 44]);
+    const pill = el([214, 0, 160, 44], [el([220, 0, 44, 44]), reference]);
+    document.body.appendChild(pill);
+    expect(paintedTriggerBox(reference, box([290, 0, 44, 44]))).toEqual(box([290, 0, 44, 44]));
+  });
+
+  it("reads a DOMRect layout box, whose sides are prototype getters", () => {
+    const reference = el([324, 61, 44, 44]);
+    document.body.appendChild(el([16, 61, 358, 44], [el([16, 61, 200, 44]), reference]));
+    class Getters {
+      get left() {
+        return 324;
+      }
+      get top() {
+        return 61;
+      }
+      get right() {
+        return 368;
+      }
+      get bottom() {
+        return 105;
+      }
+    }
+    const layout = new Getters();
+    expect(paintedTriggerBox(reference, layout)).toEqual(box([324, 61, 44, 44]));
+  });
+
+  it(`never reaches more than ${PAINTED_BOX_REACH}px past the trigger`, () => {
+    const reference = el([324, 61, 44, 44]);
+    document.body.appendChild(el([0, 61, 390, 44], [reference]));
+    expect(paintedTriggerBox(reference, box([324, 61, 44, 44]))).toEqual(box([324, 61, 44, 44]));
+  });
+});

package/src/FloatingPanel/paintedBox.ts

@@ -0,0 +1,75 @@
+export type Box = { left: number; top: number; right: number; bottom: number };
+
+/** How far a trigger's plate or press box may reach past its layout box. */
+export const PAINTED_BOX_REACH = 12;
+
+function inFlowChildren(element: Element): Element[] {
+  return Array.from(element.children).filter((child) => {
+    const style = getComputedStyle(child);
+    return style.display !== "none" && style.position !== "absolute" && style.position !== "fixed";
+  });
+}
+
+/**
+ * The box an icon trigger is seen in, which a panel covering it has to cover
+ * (LC-112, FZ-8480). A bare glyph's press box can hang past its layout slot
+ * (the trailing press slop), and a lone button's plate can be a wrapper that
+ * holds nothing else (an iOS glass capsule). Both count, up to
+ * {@link PAINTED_BOX_REACH} on any side; a wrapper shared with other content
+ * ends the walk.
+ */
+export function paintedTriggerBox(reference: Element, layout: Box): Box {
+  // A DOMRect's sides are prototype getters, so spreading it copies nothing.
+  const box = { left: layout.left, top: layout.top, right: layout.right, bottom: layout.bottom };
+  const take = (rect: DOMRect) => {
+    if (rect.width <= 0 || rect.height <= 0) return true;
+    const next = {
+      left: Math.min(box.left, rect.left),
+      top: Math.min(box.top, rect.top),
+      right: Math.max(box.right, rect.right),
+      bottom: Math.max(box.bottom, rect.bottom),
+    };
+    if (
+      layout.left - next.left > PAINTED_BOX_REACH ||
+      layout.top - next.top > PAINTED_BOX_REACH ||
+      next.right - layout.right > PAINTED_BOX_REACH ||
+      next.bottom - layout.bottom > PAINTED_BOX_REACH
+    ) {
+      return false;
+    }
+    Object.assign(box, next);
+    return true;
+  };
+  let inner: Element | null = reference;
+  while (inner) {
+    const children = inFlowChildren(inner);
+    if (children.length !== 1) break;
+    inner = children[0]!;
+    if (!take(inner.getBoundingClientRect())) break;
+  }
+  let outer: Element | null = reference.parentElement;
+  let child: Element = reference;
+  while (outer && outer.tagName !== "BODY") {
+    const children = inFlowChildren(outer);
+    if (children.length !== 1 || children[0] !== child) break;
+    if (!take(outer.getBoundingClientRect())) break;
+    child = outer;
+    outer = outer.parentElement;
+  }
+  return box;
+}
+
+/**
+ * A plate several buttons share (an iOS glass capsule around a bar's group).
+ * `data-fp-cover-surface` marks one explicitly.
+ */
+export const GROUP_SURFACE_SELECTOR = "[data-fp-cover-surface], [data-mp-glass-capsule]";
+
+/**
+ * The shared plate an icon trigger sits on, when it sits in a group (LC-112,
+ * FZ-8480 r37): the trigger's surface is the plate under it, so a panel
+ * opening from a grouped button covers the whole group.
+ */
+export function groupSurfaceOf(reference: Element): HTMLElement | null {
+  return reference.parentElement?.closest<HTMLElement>(GROUP_SURFACE_SELECTOR) ?? null;
+}

package/src/FloatingPanel/pointAnchor.spec.ts

@@ -161,6 +161,7 @@ describe("placeOverTrigger (FZ-7830, LC-112 where no sheet may take it)", () =>
       maxHeight: 600,
       shifted: false,
       end: false,
+      up: false,
     });
   });
 
@@ -276,6 +277,51 @@ describe("placeOverTrigger (FZ-7830, LC-112 where no sheet may take it)", () =>
   });
 });
 
+describe("placeOverTrigger pinned: an echoed icon trigger stays in its spot (LC-112, FZ-8480)", () => {
+  const phone: PanelBounds = { top: 57, left: 10, right: 380, bottom: 800 };
+
+  it("opens down from the button's top edge where the menu fits", () => {
+    const button = { x: 326, y: 60, width: 44, height: 44 };
+    const placed = placeOverTrigger({
+      trigger: button,
+      width: 250,
+      height: 300,
+      bounds: phone,
+      align: "auto",
+      pinned: true,
+    });
+    expect(placed).toMatchObject({ top: 60, left: 120, end: true, up: false, maxHeight: 740 });
+  });
+
+  it("opens up from the button's bottom edge near the bottom, never sliding off the button", () => {
+    const button = { x: 20, y: 740, width: 44, height: 44 };
+    const placed = placeOverTrigger({
+      trigger: button,
+      width: 250,
+      height: 300,
+      bounds: phone,
+      align: "auto",
+      pinned: true,
+    });
+    expect(placed.up).toBe(true);
+    expect(placed.top + 300).toBe(button.y + button.height);
+    expect(placed.maxHeight).toBe(button.y + button.height - phone.top);
+  });
+
+  it("scrolls from the button rather than covering past the margin when neither side fits", () => {
+    const button = { x: 20, y: 400, width: 44, height: 44 };
+    const placed = placeOverTrigger({
+      trigger: button,
+      width: 250,
+      height: 2000,
+      bounds: phone,
+      align: "auto",
+      pinned: true,
+    });
+    expect(placed).toMatchObject({ top: 400, up: false, maxHeight: 400 });
+  });
+});
+
 describe("placeBesideTrigger (FZ-7830 round 3, LC-262: beside the trigger, never over it)", () => {
   const phone: PanelBounds = { top: 57, left: 10, right: 380, bottom: 800 };
   const field = { x: 16, y: 300, width: 358, height: 44 };
@@ -289,6 +335,7 @@ describe("placeBesideTrigger (FZ-7830 round 3, LC-262: beside the trigger, never
       maxHeight: 180,
       shifted: false,
       end: false,
+      up: false,
     });
   });