@purpurds/popover 0.0.1

package/src/popover-content.test.tsx

@@ -0,0 +1,1122 @@
+import React from "react";
+import { Button } from "@purpurds/button";
+import { IconInfo } from "@purpurds/icon/info";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { axe } from "vitest-axe";
+
+import { Popover } from "./popover";
+import { PopoverButton } from "./popover-button";
+import { PopoverContent } from "./popover-content";
+import { PopoverFlow } from "./popover-flow";
+import { PopoverFooter } from "./popover-footer";
+import { PopoverTrigger } from "./popover-trigger";
+
+describe("PopoverContent", () => {
+  describe("Basic Rendering", () => {
+    it("should render with required props", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent closeIconAriaLabel="Close" title="Test" body="This is the body text" />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        expect(screen.getByText("This is the body text")).toBeInTheDocument();
+      });
+    });
+
+    it("should render with header", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent closeIconAriaLabel="Close" title="Test Title" body="Body text" />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        expect(screen.getByText("Test Title")).toBeInTheDocument();
+      });
+    });
+
+    it("should render with header icon", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent
+            closeIconAriaLabel="Close"
+            title="Test Title"
+            icon={<IconInfo data-testid="header-icon" />}
+            body="Body text"
+          />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        expect(screen.getByTestId("header-icon")).toBeInTheDocument();
+      });
+    });
+
+    it("should render close button with correct aria-label", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent closeIconAriaLabel="Close dialog" title="Test" body="Body text" />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        expect(screen.getByRole("button", { name: "Close dialog" })).toBeInTheDocument();
+      });
+    });
+
+    it("should render with custom footer", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent closeIconAriaLabel="Close" title="Test" body="Body text">
+            <PopoverFooter>
+              <PopoverButton>Custom Action</PopoverButton>
+            </PopoverFooter>
+          </PopoverContent>
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        expect(screen.getByRole("button", { name: "Custom Action" })).toBeInTheDocument();
+      });
+    });
+  });
+
+  describe("Visual Variants", () => {
+    it("should apply negative variant", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent
+            closeIconAriaLabel="Close"
+            title="Test Title"
+            body="Body text"
+            negative
+            data-testid="popover-content"
+          />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        const content = screen.getByRole("dialog");
+        expect(content).toHaveClass("purpur-popover__content--negative");
+      });
+    });
+
+    it("should apply custom className", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent
+            closeIconAriaLabel="Close"
+            title="Test Title"
+            body="Body text"
+            className="custom-class"
+          />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        const content = screen.getByTestId("popover-content");
+        expect(content).toHaveClass("custom-class");
+      });
+    });
+
+    it("should render arrow by default", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent closeIconAriaLabel="Close" title="Test" body="Body text" />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        const arrow = document.querySelector(".purpur-popover__arrow");
+        expect(arrow).toBeInTheDocument();
+      });
+    });
+
+    it("should hide arrow when beakPosition is None", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent
+            closeIconAriaLabel="Close"
+            title="Test"
+            body="Body text"
+            beakPosition="none"
+          />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        const arrow = document.querySelector(".purpur-popover__arrow");
+        expect(arrow).not.toBeInTheDocument();
+      });
+    });
+  });
+
+  describe("Positioning", () => {
+    it("should map beakPosition 'up' to Radix side 'bottom'", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent
+            closeIconAriaLabel="Close"
+            title="Test"
+            body="Body text"
+            beakPosition="up"
+          />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        const content = screen.getByTestId("popover-content");
+        expect(content).toHaveAttribute("data-side", "bottom");
+      });
+    });
+
+    it("should map beakPosition 'down' to Radix side 'top'", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent
+            closeIconAriaLabel="Close"
+            title="Test"
+            body="Body text"
+            beakPosition="down"
+          />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        const content = screen.getByTestId("popover-content");
+        expect(content).toHaveAttribute("data-side", "top");
+      });
+    });
+
+    it("should map beakPosition 'left' to Radix side 'right'", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent
+            closeIconAriaLabel="Close"
+            title="Test"
+            body="Body text"
+            beakPosition="left"
+          />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        const content = screen.getByTestId("popover-content");
+        expect(content).toHaveAttribute("data-side", "right");
+      });
+    });
+
+    it("should map beakPosition 'right' to Radix side 'left'", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent
+            closeIconAriaLabel="Close"
+            title="Test"
+            body="Body text"
+            beakPosition="right"
+          />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        const content = screen.getByTestId("popover-content");
+        expect(content).toHaveAttribute("data-side", "left");
+      });
+    });
+
+    it("should map beakPosition 'none' to Radix side 'bottom' (default)", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent
+            closeIconAriaLabel="Close"
+            title="Test"
+            body="Body text"
+            beakPosition="none"
+          />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        const content = screen.getByTestId("popover-content");
+        expect(content).toHaveAttribute("data-side", "bottom");
+      });
+    });
+
+    it("should default to 'down' (Radix 'top') when beakPosition is not provided", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent closeIconAriaLabel="Close" title="Test" body="Body text" />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        const content = screen.getByTestId("popover-content");
+        expect(content).toHaveAttribute("data-side", "top");
+      });
+    });
+
+    it("should apply custom align", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent closeIconAriaLabel="Close" title="Test" body="Body text" align="start" />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        const content = screen.getByTestId("popover-content");
+        expect(content).toHaveAttribute("data-align", "start");
+      });
+    });
+
+    it("should apply custom zIndex", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent closeIconAriaLabel="Close" title="Test" body="Body text" zIndex={999} />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        const content = screen.getByTestId("popover-content");
+        expect(content).toHaveStyle({ "--popover-z-index": "999" });
+      });
+    });
+  });
+
+  describe("Interactions", () => {
+    it("should close when close button is clicked", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent closeIconAriaLabel="Close" title="Test" body="Body text" />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        expect(screen.getByText("Body text")).toBeInTheDocument();
+      });
+
+      await user.click(screen.getByRole("button", { name: "Close" }));
+
+      await waitFor(() => {
+        expect(screen.queryByText("Body text")).not.toBeInTheDocument();
+      });
+    });
+
+    it("should call onAction when close button is clicked", async () => {
+      const onAction = vi.fn();
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent
+            closeIconAriaLabel="Close"
+            title="Test"
+            body="Body text"
+            onAction={onAction}
+          />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        expect(screen.getByText("Body text")).toBeInTheDocument();
+      });
+
+      await user.click(screen.getByRole("button", { name: "Close" }));
+
+      await waitFor(() => {
+        expect(onAction).toHaveBeenCalledWith({ type: "dismiss", step: undefined });
+      });
+    });
+
+    it("should prevent default focus behavior", async () => {
+      const preventDefault = vi.fn();
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent
+            closeIconAriaLabel="Close"
+            title="Test"
+            body="Body text"
+            onOpenAutoFocus={(e) => {
+              preventDefault();
+              e.preventDefault();
+            }}
+          />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        expect(preventDefault).toHaveBeenCalled();
+      });
+    });
+
+    it("should focus content on open", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent closeIconAriaLabel="Close" title="Test" body="Body text" />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        const content = screen.getByTestId("popover-content");
+        expect(content).toHaveAttribute("tabindex", "-1");
+      });
+    });
+  });
+
+  describe("Accessibility", () => {
+    it("should have role dialog", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent closeIconAriaLabel="Close" title="Test" body="Body text" />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        expect(screen.getByRole("dialog")).toBeInTheDocument();
+      });
+    });
+
+    it("should have aria-modal attribute", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent closeIconAriaLabel="Close" title="Test" body="Body text" />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        const content = screen.getByRole("dialog");
+        expect(content).toHaveAttribute("aria-modal", "true");
+      });
+    });
+
+    it("should use header title as aria-label", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent closeIconAriaLabel="Close" title="Important Info" body="Body text" />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        const content = screen.getByRole("dialog");
+        expect(content).toHaveAttribute("aria-labelledby", "popover-heading");
+        const heading = document.getElementById("popover-heading");
+        expect(heading).toHaveTextContent("Important Info");
+      });
+    });
+
+    it("should use custom aria-label when provided", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent
+            closeIconAriaLabel="Close"
+            title="Title"
+            body="Body text"
+            aria-label="Custom label"
+          />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        const content = screen.getByRole("dialog");
+        expect(content).toHaveAttribute("aria-label", "Custom label");
+      });
+    });
+
+    it("should have aria-hidden on arrow", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent closeIconAriaLabel="Close" title="Test" body="Body text" />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        const arrow = document.querySelector(".purpur-popover__arrow");
+        expect(arrow).toHaveAttribute("aria-hidden", "true");
+      });
+    });
+
+    it("should pass accessibility checks for content with header and footer", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent closeIconAriaLabel="Close" title="Test Title" body="Body text">
+            <PopoverFooter>
+              <PopoverButton>Got it</PopoverButton>
+            </PopoverFooter>
+          </PopoverContent>
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        expect(screen.getByText("Test Title")).toBeInTheDocument();
+      });
+
+      // Test only the content dialog, not the trigger which has known ARIA issues
+      const dialog = screen.getByRole("dialog");
+      const results = await axe(dialog);
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      expect(results).toHaveNoViolations();
+    });
+
+    it("should pass accessibility checks for content with icon", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent
+            closeIconAriaLabel="Close popover"
+            title="Information"
+            icon={<IconInfo aria-hidden="true" />}
+            body="This is important information"
+          />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        expect(screen.getByText("Information")).toBeInTheDocument();
+      });
+
+      const dialog = screen.getByRole("dialog");
+      const results = await axe(dialog);
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      expect(results).toHaveNoViolations();
+    });
+
+    it("should pass accessibility checks for negative variant", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent
+            closeIconAriaLabel="Close"
+            title="Warning"
+            body="This is a warning message"
+            negative
+          />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        expect(screen.getByText("Warning")).toBeInTheDocument();
+      });
+
+      const dialog = screen.getByRole("dialog");
+      const results = await axe(dialog);
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      expect(results).toHaveNoViolations();
+    });
+
+    it("should have proper keyboard navigation", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent closeIconAriaLabel="Close" title="Test" body="Body text">
+            <PopoverFooter>
+              <PopoverButton>Action</PopoverButton>
+            </PopoverFooter>
+          </PopoverContent>
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        expect(screen.getByRole("dialog")).toBeInTheDocument();
+      });
+
+      // Check that close button is focusable
+      const closeButton = screen.getByRole("button", { name: "Close" });
+      expect(closeButton).toHaveAttribute("type", "button");
+      expect(closeButton).not.toHaveAttribute("disabled");
+
+      // Check that action button is focusable
+      const actionButton = screen.getByRole("button", { name: "Action" });
+      expect(actionButton).toHaveAttribute("type", "button");
+      expect(actionButton).not.toHaveAttribute("disabled");
+    });
+
+    it("should have descriptive labels for screen readers", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent
+            closeIconAriaLabel="Close information dialog"
+            title="Important Information"
+            body="This is the content"
+            aria-label="Important Information"
+          />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        const dialog = screen.getByRole("dialog");
+        expect(dialog).toHaveAttribute("aria-label", "Important Information");
+        expect(dialog).toHaveAttribute("aria-modal", "true");
+      });
+
+      const closeButton = screen.getByRole("button", { name: "Close information dialog" });
+      expect(closeButton).toBeInTheDocument();
+    });
+
+    it("should pass accessibility checks for walkthrough mode", async () => {
+      render(
+        <PopoverFlow
+          separatorText="of"
+          stepText="Step"
+          backLabel="Back"
+          nextLabel="Next"
+          finishLabel="Finish"
+        >
+          <Popover multistep step={1}>
+            <PopoverTrigger>
+              <Button variant="primary">Step 1</Button>
+            </PopoverTrigger>
+            <PopoverContent closeIconAriaLabel="Close" title="Step 1" body="First step content" />
+          </Popover>
+          <Popover multistep step={2}>
+            <PopoverTrigger>
+              <Button variant="primary">Step 2</Button>
+            </PopoverTrigger>
+            <PopoverContent closeIconAriaLabel="Close" title="Step 2" body="Second step content" />
+          </Popover>
+        </PopoverFlow>
+      );
+
+      await waitFor(
+        () => {
+          expect(screen.getByText("First step content")).toBeInTheDocument();
+        },
+        { timeout: 5000 }
+      );
+
+      const dialog = screen.getByRole("dialog");
+      const results = await axe(dialog);
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      expect(results).toHaveNoViolations();
+
+      // Check that step indicator is announced to screen readers
+      const srOnlyStepText = document.querySelector('[role="status"][aria-live="polite"]');
+      expect(srOnlyStepText).toBeInTheDocument();
+      expect(srOnlyStepText).toHaveTextContent("Step 1 of 2");
+    });
+
+    it("should maintain focus trap within dialog", async () => {
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent closeIconAriaLabel="Close" title="Test" body="Body text">
+            <PopoverFooter>
+              <PopoverButton>Action 1</PopoverButton>
+            </PopoverFooter>
+          </PopoverContent>
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        expect(screen.getByRole("dialog")).toBeInTheDocument();
+      });
+
+      // Verify focus guards exist (provided by Radix UI)
+      const focusGuards = document.querySelectorAll("[data-radix-focus-guard]");
+      expect(focusGuards.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("Walkthrough Mode", () => {
+    it("should auto-generate footer for first step", async () => {
+      const onAction = vi.fn();
+      render(
+        <PopoverFlow
+          separatorText="of"
+          stepText="Step"
+          backLabel="Back"
+          nextLabel="Next"
+          finishLabel="Finish"
+        >
+          <Popover multistep step={1}>
+            <PopoverTrigger>
+              <Button variant="primary">Step 1</Button>
+            </PopoverTrigger>
+            <PopoverContent
+              closeIconAriaLabel="Close"
+              title="Step 1"
+              body="First step"
+              onAction={onAction}
+            />
+          </Popover>
+          <Popover multistep step={2}>
+            <PopoverTrigger>
+              <Button variant="primary">Step 2</Button>
+            </PopoverTrigger>
+            <PopoverContent closeIconAriaLabel="Close" title="Step 2" body="Second step" />
+          </Popover>
+        </PopoverFlow>
+      );
+
+      await waitFor(
+        () => {
+          expect(screen.getByText("First step")).toBeInTheDocument();
+        },
+        { timeout: 5000 }
+      );
+
+      expect(screen.getByRole("button", { name: "Next" })).toBeInTheDocument();
+      expect(screen.queryByRole("button", { name: "Back" })).not.toBeInTheDocument();
+    });
+
+    it("should auto-generate footer for middle step", async () => {
+      render(
+        <PopoverFlow
+          separatorText="of"
+          stepText="Step"
+          backLabel="Back"
+          nextLabel="Next"
+          finishLabel="Finish"
+          initialStep={2}
+        >
+          <Popover multistep step={1}>
+            <PopoverTrigger>
+              <Button variant="primary">Step 1</Button>
+            </PopoverTrigger>
+            <PopoverContent closeIconAriaLabel="Close" title="Step 1" body="First step" />
+          </Popover>
+          <Popover multistep step={2}>
+            <PopoverTrigger>
+              <Button variant="primary">Step 2</Button>
+            </PopoverTrigger>
+            <PopoverContent closeIconAriaLabel="Close" title="Step 2" body="Second step" />
+          </Popover>
+          <Popover multistep step={3}>
+            <PopoverTrigger>
+              <Button variant="primary">Step 3</Button>
+            </PopoverTrigger>
+            <PopoverContent closeIconAriaLabel="Close" title="Step 3" body="Third step" />
+          </Popover>
+        </PopoverFlow>
+      );
+
+      await waitFor(
+        () => {
+          expect(screen.getByText("Second step")).toBeInTheDocument();
+        },
+        { timeout: 5000 }
+      );
+
+      expect(screen.getByRole("button", { name: "Next" })).toBeInTheDocument();
+      expect(screen.getByRole("button", { name: "Back" })).toBeInTheDocument();
+    });
+
+    it("should auto-generate footer for last step", async () => {
+      render(
+        <PopoverFlow
+          separatorText="of"
+          stepText="Step"
+          backLabel="Back"
+          nextLabel="Next"
+          finishLabel="Finish"
+          initialStep={2}
+        >
+          <Popover multistep step={1}>
+            <PopoverTrigger>
+              <Button variant="primary">Step 1</Button>
+            </PopoverTrigger>
+            <PopoverContent closeIconAriaLabel="Close" title="Step 1" body="First step" />
+          </Popover>
+          <Popover multistep step={2}>
+            <PopoverTrigger>
+              <Button variant="primary">Step 2</Button>
+            </PopoverTrigger>
+            <PopoverContent closeIconAriaLabel="Close" title="Step 2" body="Second step" />
+          </Popover>
+        </PopoverFlow>
+      );
+
+      await waitFor(
+        () => {
+          expect(screen.getByText("Second step")).toBeInTheDocument();
+        },
+        { timeout: 5000 }
+      );
+
+      expect(screen.getByRole("button", { name: "Finish" })).toBeInTheDocument();
+      expect(screen.getByRole("button", { name: "Back" })).toBeInTheDocument();
+    });
+
+    it("should call onAction with correct step on back click", async () => {
+      const onAction = vi.fn();
+      const user = userEvent.setup({ delay: null });
+      render(
+        <PopoverFlow
+          separatorText="of"
+          stepText="Step"
+          backLabel="Back"
+          nextLabel="Next"
+          finishLabel="Finish"
+          initialStep={2}
+        >
+          <Popover multistep step={1}>
+            <PopoverTrigger>
+              <Button variant="primary">Step 1</Button>
+            </PopoverTrigger>
+            <PopoverContent closeIconAriaLabel="Close" title="Step 1" body="First step" />
+          </Popover>
+          <Popover multistep step={2}>
+            <PopoverTrigger>
+              <Button variant="primary">Step 2</Button>
+            </PopoverTrigger>
+            <PopoverContent
+              closeIconAriaLabel="Close"
+              title="Step 2"
+              body="Second step"
+              onAction={onAction}
+            />
+          </Popover>
+        </PopoverFlow>
+      );
+
+      await waitFor(
+        () => {
+          expect(screen.getByRole("button", { name: "Back" })).toBeInTheDocument();
+        },
+        { timeout: 5000 }
+      );
+
+      await user.click(screen.getByRole("button", { name: "Back" }));
+
+      expect(onAction).toHaveBeenCalledWith({ type: "back", step: 2 });
+    });
+
+    it("should call onAction with correct step on next click", async () => {
+      const onAction = vi.fn();
+      const user = userEvent.setup({ delay: null });
+      render(
+        <PopoverFlow
+          separatorText="of"
+          stepText="Step"
+          backLabel="Back"
+          nextLabel="Next"
+          finishLabel="Finish"
+        >
+          <Popover multistep step={1}>
+            <PopoverTrigger>
+              <Button variant="primary">Step 1</Button>
+            </PopoverTrigger>
+            <PopoverContent
+              closeIconAriaLabel="Close"
+              title="Step 1"
+              body="First step"
+              onAction={onAction}
+            />
+          </Popover>
+          <Popover multistep step={2}>
+            <PopoverTrigger>
+              <Button variant="primary">Step 2</Button>
+            </PopoverTrigger>
+            <PopoverContent closeIconAriaLabel="Close" title="Step 2" body="Second step" />
+          </Popover>
+        </PopoverFlow>
+      );
+
+      await waitFor(
+        () => {
+          expect(screen.getByRole("button", { name: "Next" })).toBeInTheDocument();
+        },
+        { timeout: 5000 }
+      );
+
+      await user.click(screen.getByRole("button", { name: "Next" }));
+
+      expect(onAction).toHaveBeenCalledWith({ type: "next", step: 1 });
+    });
+
+    it("should call onAction with correct step on finish click", async () => {
+      const onAction = vi.fn();
+      const user = userEvent.setup({ delay: null });
+      render(
+        <PopoverFlow
+          separatorText="of"
+          stepText="Step"
+          backLabel="Back"
+          nextLabel="Next"
+          finishLabel="Finish"
+          initialStep={2}
+        >
+          <Popover multistep step={1}>
+            <PopoverTrigger>
+              <Button variant="primary">Step 1</Button>
+            </PopoverTrigger>
+            <PopoverContent closeIconAriaLabel="Close" title="Step 1" body="First step" />
+          </Popover>
+          <Popover multistep step={2}>
+            <PopoverTrigger>
+              <Button variant="primary">Step 2</Button>
+            </PopoverTrigger>
+            <PopoverContent
+              closeIconAriaLabel="Close"
+              title="Step 2"
+              body="Second step"
+              onAction={onAction}
+            />
+          </Popover>
+        </PopoverFlow>
+      );
+
+      await waitFor(
+        () => {
+          expect(screen.getByRole("button", { name: "Finish" })).toBeInTheDocument();
+        },
+        { timeout: 5000 }
+      );
+
+      await user.click(screen.getByRole("button", { name: "Finish" }));
+
+      expect(onAction).toHaveBeenCalledWith({ type: "finish", step: 2 });
+    });
+
+    it("should not override custom footer in walkthrough mode", async () => {
+      render(
+        <PopoverFlow
+          separatorText="of"
+          stepText="Step"
+          backLabel="Back"
+          nextLabel="Next"
+          finishLabel="Finish"
+        >
+          <Popover multistep step={1}>
+            <PopoverTrigger>
+              <Button variant="primary">Step 1</Button>
+            </PopoverTrigger>
+            <PopoverContent closeIconAriaLabel="Close" title="Step 1" body="First step">
+              <PopoverFooter>
+                <PopoverButton>Custom Footer</PopoverButton>
+              </PopoverFooter>
+            </PopoverContent>
+          </Popover>
+          <Popover multistep step={2}>
+            <PopoverTrigger>
+              <Button variant="primary">Step 2</Button>
+            </PopoverTrigger>
+            <PopoverContent closeIconAriaLabel="Close" title="Step 2" body="Second step" />
+          </Popover>
+        </PopoverFlow>
+      );
+
+      await waitFor(
+        () => {
+          expect(screen.getByRole("button", { name: "Custom Footer" })).toBeInTheDocument();
+        },
+        { timeout: 5000 }
+      );
+
+      expect(screen.queryByRole("button", { name: "Next" })).not.toBeInTheDocument();
+    });
+  });
+
+  describe("Forward Ref", () => {
+    it("should forward ref to content element", async () => {
+      const ref = React.createRef<HTMLDivElement>();
+      const user = userEvent.setup({ delay: null });
+      render(
+        <Popover>
+          <PopoverTrigger>
+            <Button variant="primary">Trigger</Button>
+          </PopoverTrigger>
+          <PopoverContent ref={ref} closeIconAriaLabel="Close" title="Test" body="Body text" />
+        </Popover>
+      );
+
+      await user.click(screen.getByRole("button", { name: "Trigger" }));
+
+      await waitFor(() => {
+        expect(ref.current).toBeInstanceOf(HTMLElement);
+      });
+    });
+  });
+});