@simplybusiness/mobius 10.4.1 → 10.4.3

package/dist/types/components/Popover/Arrow.d.ts

@@ -0,0 +1,9 @@
+import type { CSSProperties, Ref } from "react";
+interface ArrowProps {
+    ref?: Ref<SVGSVGElement>;
+    width?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+export declare const Arrow: ({ ref, width, className, style }: ArrowProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/components/Popover/useAutoUpdate.d.ts

@@ -0,0 +1,9 @@
+import type { RefObject } from "react";
+interface UseAutoUpdateArgs {
+    referenceRef: RefObject<HTMLElement | null>;
+    floatingRef: RefObject<HTMLDivElement | null>;
+    onUpdate: () => void;
+    enabled: boolean;
+}
+export declare const useAutoUpdate: ({ referenceRef, floatingRef, onUpdate, enabled, }: UseAutoUpdateArgs) => void;
+export {};

package/dist/types/components/Popover/useFloatingPosition.d.ts

@@ -0,0 +1,17 @@
+import type { CSSProperties, RefObject } from "react";
+interface UseFloatingPositionArgs {
+    referenceRef: RefObject<HTMLElement | null>;
+    floatingRef: RefObject<HTMLDivElement | null>;
+    arrowRef: RefObject<SVGSVGElement | null>;
+    isOpen: boolean;
+    offsetPx: number;
+    arrowWidth: number;
+    useFixedStrategy: boolean;
+}
+interface UseFloatingPositionResult {
+    initialFloatingStyles: CSSProperties;
+    initialArrowStyles: CSSProperties;
+    update: () => void;
+}
+export declare const useFloatingPosition: ({ referenceRef, floatingRef, arrowRef, isOpen, offsetPx, arrowWidth, useFixedStrategy, }: UseFloatingPositionArgs) => UseFloatingPositionResult;
+export {};

package/dist/types/components/Popover/useOutsidePress.d.ts

@@ -0,0 +1,9 @@
+import type { RefObject } from "react";
+interface UseOutsidePressArgs {
+    referenceRef: RefObject<HTMLElement | null>;
+    floatingRef: RefObject<HTMLDivElement | null>;
+    enabled: boolean;
+    onOutsidePress: (event: PointerEvent) => void;
+}
+export declare const useOutsidePress: ({ referenceRef, floatingRef, enabled, onOutsidePress, }: UseOutsidePressArgs) => void;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@simplybusiness/mobius",
   "license": "UNLICENSED",
-  "version": "10.4.1",
+  "version": "10.4.3",
   "description": "Core library of Mobius react components",
   "repository": {
     "type": "git",
@@ -96,10 +96,9 @@
     "react-dom": "^19.2.0"
   },
   "dependencies": {
-    "@floating-ui/react": "^0.27.19",
     "@loadable/component": "^5.16.7",
     "@simplybusiness/icons": "^5.1.0",
-    "@simplybusiness/mobius-hooks": "^0.1.1",
+    "@simplybusiness/mobius-hooks": "^0.2.0",
     "classnames": "^2.5.1",
     "dialog-polyfill": "^0.5.6",
     "react-accessible-dropdown-menu-hook": "^4.0.1",

package/src/components/Popover/Arrow.tsx

@@ -0,0 +1,25 @@
+import type { CSSProperties, Ref } from "react";
+
+interface ArrowProps {
+  ref?: Ref<SVGSVGElement>;
+  width?: number;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export const Arrow = ({ ref, width = 20, className, style }: ArrowProps) => {
+  const height = width / 2;
+  return (
+    <svg
+      ref={ref}
+      className={className}
+      aria-hidden="true"
+      width={width}
+      height={height}
+      viewBox={`0 0 ${width} ${height}`}
+      style={style}
+    >
+      <path d={`M0,0 H${width} L${width / 2},${height} Z`} />
+    </svg>
+  );
+};

package/src/components/Popover/Popover.characterization.test.tsx

@@ -0,0 +1,269 @@
+/**
+ * Characterization ("golden") tests — freeze the observable API surface of
+ * Popover. Added to guard the swap from @floating-ui/react to a local
+ * implementation; retained as a long-lived contract test.
+ *
+ * Pixel math (flip/shift/offset values) is NOT asserted here — jsdom has no
+ * layout. Those are verified manually in Storybook.
+ */
+import { fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Popover } from ".";
+
+describe("Popover — characterization (API contract)", () => {
+  describe("trigger element", () => {
+    it("renders the trigger as the cloned child with merged class names", () => {
+      render(
+        <Popover
+          trigger={
+            <button type="button" className="my-trigger">
+              Toggle
+            </button>
+          }
+        >
+          Body
+        </Popover>,
+      );
+
+      const trigger = screen.getByText("Toggle");
+      expect(trigger.tagName).toBe("BUTTON");
+      expect(trigger).toHaveClass("my-trigger", "mobius-popover__toggle");
+    });
+
+    it("does not wrap the trigger in an extra element", () => {
+      const { container } = render(
+        <Popover trigger={<button type="button">Toggle</button>}>Body</Popover>,
+      );
+      expect(container.firstElementChild?.tagName).toBe("BUTTON");
+    });
+  });
+
+  describe("floating container (when open)", () => {
+    const open = () => {
+      render(
+        <Popover trigger={<button type="button">Toggle</button>}>Body</Popover>,
+      );
+      fireEvent.click(screen.getByText("Toggle"));
+      return document.querySelector(
+        ".mobius-popover__container",
+      ) as HTMLDivElement;
+    };
+
+    it("is not in the DOM when closed", () => {
+      render(
+        <Popover trigger={<button type="button">Toggle</button>}>Body</Popover>,
+      );
+      expect(document.querySelector(".mobius-popover__container")).toBeNull();
+    });
+
+    it("is portalled to document.body when open", () => {
+      const floating = open();
+      expect(floating).toHaveClass("mobius", "mobius-popover__container");
+      expect(floating.parentElement).toBe(document.body);
+    });
+
+    it("uses a viewport-anchored positioning strategy", () => {
+      // Local implementation uses position: absolute with document-relative
+      // top/left (viewport rect + window.scrollY/X). Because the popover is
+      // portalled to document.body, the initial containing block is the
+      // document, so absolute coords pin it to the trigger and scroll
+      // natively with the page.
+      const floating = open();
+      expect(["fixed", "absolute"]).toContain(floating.style.position);
+    });
+
+    it("has inline top/left styles applied", () => {
+      const floating = open();
+      expect(floating).not.toHaveStyle({ top: "" });
+      expect(floating).not.toHaveStyle({ left: "" });
+    });
+  });
+
+  describe("arrow element", () => {
+    it("renders an SVG with the arrow class and aria-hidden", () => {
+      render(
+        <Popover trigger={<button type="button">Toggle</button>}>Body</Popover>,
+      );
+      fireEvent.click(screen.getByText("Toggle"));
+      const arrow = document.querySelector("svg.mobius-popover__arrow-icon");
+      expect(arrow).not.toBeNull();
+      expect(arrow).toHaveAttribute("aria-hidden", "true");
+      expect(arrow).toHaveStyle({ position: "absolute" });
+    });
+  });
+});
+
+describe("Popover — characterization (dismiss semantics)", () => {
+  it("closes and fires onClose when pressing outside via pointerdown", () => {
+    const onClose = vi.fn();
+    render(
+      <div>
+        <Popover
+          trigger={<button type="button">Toggle</button>}
+          onClose={onClose}
+        >
+          Body
+        </Popover>
+        <button type="button" data-testid="outside">
+          Outside
+        </button>
+      </div>,
+    );
+
+    fireEvent.click(screen.getByText("Toggle"));
+    expect(screen.getByText("Body")).toBeInTheDocument();
+
+    fireEvent.pointerDown(screen.getByTestId("outside"));
+
+    expect(screen.queryByText("Body")).not.toBeInTheDocument();
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not fire onClose when pointerdown lands on the toggle itself", () => {
+    const onClose = vi.fn();
+    render(
+      <Popover
+        trigger={<button type="button">Toggle</button>}
+        onClose={onClose}
+      >
+        Body
+      </Popover>,
+    );
+
+    fireEvent.click(screen.getByText("Toggle"));
+    expect(screen.getByText("Body")).toBeInTheDocument();
+
+    fireEvent.pointerDown(screen.getByText("Toggle"));
+    fireEvent.click(screen.getByText("Toggle"));
+
+    expect(screen.queryByText("Body")).not.toBeInTheDocument();
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not close when pointerdown lands inside the floating container", () => {
+    const onClose = vi.fn();
+    render(
+      <Popover
+        trigger={<button type="button">Toggle</button>}
+        onClose={onClose}
+      >
+        <span>Body</span>
+      </Popover>,
+    );
+
+    fireEvent.click(screen.getByText("Toggle"));
+    fireEvent.pointerDown(screen.getByText("Body"));
+
+    expect(screen.getByText("Body")).toBeInTheDocument();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("closes on Escape and fires onClose", () => {
+    const onClose = vi.fn();
+    render(
+      <Popover
+        trigger={<button type="button">Toggle</button>}
+        onClose={onClose}
+      >
+        Body
+      </Popover>,
+    );
+
+    fireEvent.click(screen.getByText("Toggle"));
+    expect(screen.getByText("Body")).toBeInTheDocument();
+
+    fireEvent.keyDown(window, { key: "Escape" });
+
+    expect(screen.queryByText("Body")).not.toBeInTheDocument();
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("Popover — characterization (auto-update subscriptions)", () => {
+  let windowAddSpy: ReturnType<typeof vi.spyOn>;
+  let windowRemoveSpy: ReturnType<typeof vi.spyOn>;
+  let resizeObserverInstances: Array<{
+    observe: ReturnType<typeof vi.fn>;
+    unobserve: ReturnType<typeof vi.fn>;
+    disconnect: ReturnType<typeof vi.fn>;
+  }>;
+
+  beforeEach(() => {
+    resizeObserverInstances = [];
+    class MockResizeObserver {
+      observe = vi.fn();
+      unobserve = vi.fn();
+      disconnect = vi.fn();
+      constructor() {
+        resizeObserverInstances.push(this);
+      }
+    }
+    vi.stubGlobal("ResizeObserver", MockResizeObserver);
+    windowAddSpy = vi.spyOn(window, "addEventListener");
+    windowRemoveSpy = vi.spyOn(window, "removeEventListener");
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    windowAddSpy.mockRestore();
+    windowRemoveSpy.mockRestore();
+  });
+
+  const scrollListeners = () =>
+    windowAddSpy.mock.calls.filter((c: unknown[]) => c[0] === "scroll");
+  const resizeListeners = () =>
+    windowAddSpy.mock.calls.filter((c: unknown[]) => c[0] === "resize");
+
+  it("subscribes to window scroll when opened", () => {
+    render(
+      <Popover trigger={<button type="button">Toggle</button>}>Body</Popover>,
+    );
+    expect(scrollListeners().length).toBe(0);
+
+    fireEvent.click(screen.getByText("Toggle"));
+
+    expect(scrollListeners().length).toBeGreaterThan(0);
+  });
+
+  it("subscribes to window resize when opened", () => {
+    render(
+      <Popover trigger={<button type="button">Toggle</button>}>Body</Popover>,
+    );
+    fireEvent.click(screen.getByText("Toggle"));
+    expect(resizeListeners().length).toBeGreaterThan(0);
+  });
+
+  it("creates a ResizeObserver that observes reference + floating elements", () => {
+    render(
+      <Popover trigger={<button type="button">Toggle</button>}>Body</Popover>,
+    );
+    fireEvent.click(screen.getByText("Toggle"));
+
+    const totalObserves = resizeObserverInstances.reduce(
+      (n, ro) => n + ro.observe.mock.calls.length,
+      0,
+    );
+    expect(totalObserves).toBeGreaterThanOrEqual(2);
+  });
+
+  it("removes scroll/resize listeners when closed", () => {
+    render(
+      <Popover trigger={<button type="button">Toggle</button>}>Body</Popover>,
+    );
+    fireEvent.click(screen.getByText("Toggle"));
+    const scrollAdded: number = scrollListeners().length;
+    const resizeAdded: number = resizeListeners().length;
+
+    fireEvent.click(screen.getByLabelText("Close"));
+
+    const scrollRemoved: number = windowRemoveSpy.mock.calls.filter(
+      (c: unknown[]) => c[0] === "scroll",
+    ).length;
+    const resizeRemoved: number = windowRemoveSpy.mock.calls.filter(
+      (c: unknown[]) => c[0] === "resize",
+    ).length;
+
+    expect(scrollRemoved).toBeGreaterThanOrEqual(scrollAdded);
+    expect(resizeRemoved).toBeGreaterThanOrEqual(resizeAdded);
+  });
+});

package/src/components/Popover/Popover.stories.tsx

@@ -1,9 +1,10 @@
-import type { Meta, StoryObj } from "@storybook/react";
 import { circleQuestion } from "@simplybusiness/icons";
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
 import type { PopoverProps } from "..";
-import { Button, Flex, Popover, Icon } from "..";
+import { Button, Flex, Icon, Modal, Popover } from "..";
 import { excludeControls } from "../../utils";
-// eslint-disable-next-line no-restricted-imports -- story-only styles
+
 import "./Popover.story.styles.css";
 
 type StoryType = StoryObj<typeof Popover>;
@@ -46,4 +47,40 @@ export const CustomTrigger: StoryType = {
   ),
 };
 
+export const NearBottomEdge: StoryType = {
+  render: () => (
+    <div style={{ marginTop: "90vh" }}>
+      <Popover trigger={<Button variant="primary">Open — flips to top</Button>}>
+        Near the bottom edge: the popover flips above the trigger so it stays in
+        the viewport.
+      </Popover>
+    </div>
+  ),
+};
+
+const InsideModalDemo = () => {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Open modal</Button>
+      <Modal isOpen={open} onClose={() => setOpen(false)} closeLabel="Close">
+        <Modal.Header>Popover inside a modal</Modal.Header>
+        <Modal.Content>
+          <p>
+            The popover must render above the modal backdrop. Click the trigger
+            below.
+          </p>
+          <Popover trigger={<Button variant="primary">Open popover</Button>}>
+            Visible above the modal backdrop.
+          </Popover>
+        </Modal.Content>
+      </Modal>
+    </>
+  );
+};
+
+export const InsideModal: StoryType = {
+  render: () => <InsideModalDemo />,
+};
+
 export default meta;

package/src/components/Popover/Popover.test.tsx

@@ -62,7 +62,9 @@ describe("Popover", () => {
 
       fireEvent.click(button);
 
-      const popoverContainer = button.nextSibling;
+      const popoverContainer = document.querySelector(
+        `.${CONTAINER_CLASS_NAME}`,
+      );
 
       await waitFor(() => {
         expect(popoverContainer).toHaveClass("mobius");
@@ -97,7 +99,9 @@ describe("Popover", () => {
 
       fireEvent.click(button);
 
-      const popoverContainer = button.nextSibling;
+      const popoverContainer = document.querySelector(
+        `.${CONTAINER_CLASS_NAME}`,
+      );
 
       await waitFor(() => {
         expect(popoverContainer).toHaveClass(customClassName);

package/src/components/Popover/Popover.tsx

@@ -1,22 +1,16 @@
-import {
-  FloatingArrow,
-  arrow,
-  autoUpdate,
-  flip,
-  offset,
-  shift,
-  useDismiss,
-  useFloating,
-  useInteractions,
-} from "@floating-ui/react";
 import { cross } from "@simplybusiness/icons";
 import classNames from "classnames/dedupe";
 import type { ReactElement, ReactNode, RefAttributes } from "react";
 import { cloneElement, useCallback, useEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
 import { useWindowEvent } from "@simplybusiness/mobius-hooks";
 import type { DOMProps } from "../../types";
 import { Button } from "../Button";
 import { Icon } from "../Icon";
+import { Arrow } from "./Arrow";
+import { useAutoUpdate } from "./useAutoUpdate";
+import { useFloatingPosition } from "./useFloatingPosition";
+import { useOutsidePress } from "./useOutsidePress";
 import "./Popover.css";
 
 export type PopoverElementType = HTMLDivElement;
@@ -34,38 +28,46 @@ export interface PopoverProps
 }
 
 const OFFSET_FROM_CONTENT_DEFAULT = 10;
+const ARROW_WIDTH = 20;
 
 export const Popover = (props: PopoverProps) => {
   const { trigger, children, onOpen, onClose, className } = props;
-  const arrowRef = useRef(null);
-  const floatingContainerRef = useRef<HTMLDivElement | null>(null);
+  const referenceRef = useRef<HTMLElement | null>(null);
+  const floatingRef = useRef<HTMLDivElement | null>(null);
+  const arrowRef = useRef<SVGSVGElement | null>(null);
   const [isOpen, setIsOpen] = useState(false);
-  const { refs, floatingStyles, context } = useFloating({
-    open: isOpen,
-    onOpenChange: setIsOpen,
-    whileElementsMounted: autoUpdate,
-    middleware: [
-      arrow({
-        element: arrowRef,
-      }),
-      offset(OFFSET_FROM_CONTENT_DEFAULT),
-      shift(),
-      flip(),
-    ],
+  const [portalTarget, setPortalTarget] = useState<HTMLElement | null>(null);
+
+  const isInsideDialog =
+    portalTarget !== null && portalTarget.tagName === "DIALOG";
+
+  const { initialFloatingStyles, initialArrowStyles, update } =
+    useFloatingPosition({
+      referenceRef,
+      floatingRef,
+      arrowRef,
+      isOpen,
+      offsetPx: OFFSET_FROM_CONTENT_DEFAULT,
+      arrowWidth: ARROW_WIDTH,
+      useFixedStrategy: isInsideDialog,
+    });
+
+  useAutoUpdate({
+    referenceRef,
+    floatingRef,
+    onUpdate: update,
+    enabled: isOpen,
   });
-  const dismiss = useDismiss(context, {
-    bubbles: true,
-    outsidePress: (event: MouseEvent) => {
-      // Prevent 'onClose' from firing when clicking the toggle to close
-      const toggle = refs.reference.current as HTMLElement;
-      const isToggleClick = !toggle?.contains(event.target as HTMLElement);
-      if (isToggleClick) {
-        onClose?.();
-      }
-      return true;
+
+  useOutsidePress({
+    referenceRef,
+    floatingRef,
+    enabled: isOpen,
+    onOutsidePress: () => {
+      onClose?.();
+      setIsOpen(false);
     },
   });
-  const { getReferenceProps, getFloatingProps } = useInteractions([dismiss]);
 
   const containerClasses = classNames(
     "mobius",
@@ -73,19 +75,11 @@ export const Popover = (props: PopoverProps) => {
     className,
   );
 
-  const setFloatingRef = useCallback(
-    (node: HTMLDivElement | null) => {
-      refs.setFloating(node);
-      floatingContainerRef.current = node;
-    },
-    [refs],
-  );
-
   // Native listener to prevent clicks inside the popover from activating
   // interactive ancestors. Must be native because React's onClick fires
   // too late via delegation.
   useEffect(() => {
-    const el = floatingContainerRef.current;
+    const el = floatingRef.current;
     if (!el) return;
 
     const preventLabelActivation = (e: Event) => {
@@ -107,64 +101,76 @@ export const Popover = (props: PopoverProps) => {
       return;
     }
 
+    // Portal into the nearest open <dialog> ancestor so the popover renders
+    // in the same top-layer as the dialog. document.body falls outside that
+    // top-layer and paints beneath the modal backdrop.
+    const dialog = referenceRef.current?.closest("dialog");
+    setPortalTarget(dialog ?? document.body);
     setIsOpen(true);
     onOpen?.();
   };
 
+  const setReferenceRef = useCallback((node: HTMLElement | null) => {
+    referenceRef.current = node;
+  }, []);
+
   const triggerComponent = cloneElement(trigger, {
-    ref: refs.setReference,
+    ref: setReferenceRef,
     className: classNames(
       (trigger.props as { className?: string }).className,
       "mobius-popover__toggle",
     ),
     onClick: toggleVisibility,
-    ...getReferenceProps(),
   } as Record<string, unknown>);
 
   useWindowEvent("keydown", e => {
-    if (e.key === "Escape") {
+    if (e.key === "Escape" && isOpen) {
+      setIsOpen(false);
       onClose?.();
       e.preventDefault();
       e.stopPropagation();
     }
   });
 
+  const floatingElement = isOpen ? (
+    <div
+      className={containerClasses}
+      ref={floatingRef}
+      style={initialFloatingStyles}
+    >
+      <div className="mobius-popover">
+        <header className="mobius-popover__header">
+          <Button
+            type="button"
+            className="mobius-popover__close-button"
+            onClick={toggleVisibility}
+            aria-label="Close"
+            variant="ghost"
+          >
+            <Icon
+              icon={cross}
+              size="md"
+              className="mobius-popover__close-icon"
+            />
+          </Button>
+        </header>
+        <div className="mobius-popover__body">{children}</div>
+      </div>
+      <Arrow
+        ref={arrowRef}
+        style={initialArrowStyles}
+        className="mobius-popover__arrow-icon"
+        width={ARROW_WIDTH}
+      />
+    </div>
+  ) : null;
+
   return (
     <>
       {triggerComponent}
-      {isOpen && (
-        <div
-          className={containerClasses}
-          ref={setFloatingRef}
-          style={floatingStyles}
-          {...getFloatingProps()}
-        >
-          <div className="mobius-popover">
-            <header className="mobius-popover__header">
-              <Button
-                type="button"
-                className="mobius-popover__close-button"
-                onClick={toggleVisibility}
-                aria-label="Close"
-                variant="ghost"
-              >
-                <Icon
-                  icon={cross}
-                  size="md"
-                  className="mobius-popover__close-icon"
-                />
-              </Button>
-            </header>
-            <div className="mobius-popover__body">{children}</div>
-          </div>
-          <FloatingArrow
-            ref={arrowRef}
-            context={context}
-            width={20}
-            className="mobius-popover__arrow-icon"
-          />
-        </div>
-      )}
+      {floatingElement && portalTarget
+        ? createPortal(floatingElement, portalTarget)
+        : null}
     </>
   );
 };