@purpurds/popover 0.0.1

package/src/popover-standalone.tsx

@@ -0,0 +1,48 @@
+import React, { type ReactNode, useState } from "react";
+import * as RadixPopover from "@radix-ui/react-popover";
+
+import { PopoverInternalContext } from "./popover-internal-context";
+
+export type PopoverStandaloneProps = RadixPopover.PopoverProps & {
+  children: ReactNode;
+  className?: string;
+  disableClickOutside?: boolean;
+};
+
+export const PopoverStandalone = ({
+  children,
+  open: controlledOpen,
+  defaultOpen = false,
+  onOpenChange,
+  disableClickOutside,
+  ...props
+}: PopoverStandaloneProps) => {
+  // Internal state for uncontrolled mode
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+
+  const isControlled = controlledOpen !== undefined;
+  const isOpen = isControlled ? controlledOpen : internalOpen;
+
+  const handleOpenChange = (newOpen: boolean) => {
+    if (!isControlled) {
+      setInternalOpen(newOpen);
+    }
+    onOpenChange?.(newOpen);
+  };
+
+  return (
+    <RadixPopover.Root open={isOpen} onOpenChange={handleOpenChange} {...props}>
+      <PopoverInternalContext.Provider
+        value={{
+          isOpen,
+          walkthroughStep: 0,
+          disableClickOutside,
+        }}
+      >
+        {children}
+      </PopoverInternalContext.Provider>
+    </RadixPopover.Root>
+  );
+};
+
+PopoverStandalone.displayName = "PopoverStandalone";

package/src/popover-steps.tsx

@@ -0,0 +1,32 @@
+import React from "react";
+import { Paragraph } from "@purpurds/paragraph";
+import c from "classnames/bind";
+
+import styles from "./popover.module.scss";
+import { usePopoverFlow } from "./popover-flow";
+import { usePopoverInternal } from "./popover-internal-context";
+
+const cx = c.bind(styles);
+
+export const PopoverSteps = () => {
+  const flow = usePopoverFlow();
+  const context = usePopoverInternal();
+
+  // Use walkthroughStep from context (each popover knows its own step number)
+  const currentStep = context?.walkthroughStep || flow.currentStep;
+  const { totalSteps, separatorText, stepText } = flow;
+  return (
+    <>
+      <Paragraph
+        className={cx("purpur-popover__steps")}
+        role="status"
+        aria-live="polite"
+        aria-atomic="true"
+      >
+        {stepText} {currentStep} {separatorText} {totalSteps}
+      </Paragraph>
+    </>
+  );
+};
+
+PopoverSteps.displayName = "PopoverSteps";

package/src/popover-trigger.tsx

@@ -0,0 +1,71 @@
+import React, { forwardRef } from "react";
+import * as RadixPopover from "@radix-ui/react-popover";
+import c from "classnames/bind";
+
+import styles from "./popover.module.scss";
+import { usePopoverTrigger } from "./usePopoverTrigger";
+
+const cx = c.bind(styles);
+
+export type PopoverTriggerProps = RadixPopover.PopoverTriggerProps & {
+  /**
+   * Whether to show visual highlight effect around the trigger when popover is open.
+   * @default true
+   */
+  highlight?: boolean;
+  /**
+   * Whether to use negative (light) styling for the highlight effect.
+   * @default false
+   */
+  negative?: boolean;
+};
+
+export const PopoverTrigger = forwardRef<HTMLButtonElement, PopoverTriggerProps>(
+  ({ children, className, highlight = true, negative = false, ...props }, ref) => {
+    const { triggerRef, context } = usePopoverTrigger(ref);
+
+    return (
+      <div
+        className={cx(
+          "purpur-popover__trigger",
+          { "purpur-popover__trigger--highlight": context?.isOpen && highlight },
+          className
+        )}
+      >
+        {context?.isOpen && highlight && (
+          <>
+            {/* State 1: Outer glow effect */}
+            <div
+              className={cx(
+                "purpur-popover__trigger-highlight",
+                "purpur-popover__trigger-highlight--state1",
+                { "purpur-popover__trigger-highlight--negative": negative }
+              )}
+              aria-hidden="true"
+            />
+            {/* State 2: Inner border only */}
+            <div
+              className={cx(
+                "purpur-popover__trigger-highlight",
+                "purpur-popover__trigger-highlight--state2",
+                { "purpur-popover__trigger-highlight--negative": negative }
+              )}
+              aria-hidden="true"
+            />
+          </>
+        )}
+        <RadixPopover.Trigger
+          ref={triggerRef}
+          asChild
+          aria-expanded={context?.isOpen ?? false}
+          aria-haspopup="dialog"
+          {...props}
+        >
+          {children}
+        </RadixPopover.Trigger>
+      </div>
+    );
+  }
+);
+
+PopoverTrigger.displayName = "PopoverTrigger";

package/src/popover-walkthrough.test.tsx

@@ -0,0 +1,346 @@
+import React from "react";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { Popover } from "./popover";
+import { type PopoverAction, PopoverContent } from "./popover-content";
+import { PopoverFlow } from "./popover-flow";
+import { PopoverTrigger } from "./popover-trigger";
+
+describe("Popover Walkthrough Integration Tests", () => {
+  let user: ReturnType<typeof userEvent.setup>;
+
+  beforeEach(() => {
+    user = userEvent.setup();
+    // Mock scrollTo for tests
+    window.scrollTo = vi.fn();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  const ThreeStepWalkthrough = ({ onAction }: { onAction?: (action: PopoverAction) => void }) => {
+    return (
+      <PopoverFlow
+        separatorText="of"
+        stepText="Step"
+        backLabel="Back"
+        nextLabel="Next"
+        finishLabel="Finish"
+      >
+        <div data-testid="step-1-container">
+          <Popover multistep step={1}>
+            <PopoverTrigger>
+              <button>Step 1 Trigger</button>
+            </PopoverTrigger>
+            <PopoverContent
+              beakPosition="down"
+              closeIconAriaLabel="Close"
+              title="Step 1"
+              body="This is step 1"
+              onAction={onAction}
+            />
+          </Popover>
+        </div>
+
+        <div data-testid="step-2-container">
+          <Popover multistep step={2}>
+            <PopoverTrigger>
+              <button>Step 2 Trigger</button>
+            </PopoverTrigger>
+            <PopoverContent
+              beakPosition="down"
+              closeIconAriaLabel="Close"
+              title="Step 2"
+              body="This is step 2"
+              onAction={onAction}
+            />
+          </Popover>
+        </div>
+
+        <div data-testid="step-3-container">
+          <Popover multistep step={3}>
+            <PopoverTrigger>
+              <button>Step 3 Trigger</button>
+            </PopoverTrigger>
+            <PopoverContent
+              beakPosition="down"
+              closeIconAriaLabel="Close"
+              title="Step 3"
+              body="This is step 3"
+              onAction={onAction}
+            />
+          </Popover>
+        </div>
+      </PopoverFlow>
+    );
+  };
+
+  it("should auto-open the first step when mounted", async () => {
+    render(<ThreeStepWalkthrough />);
+
+    // Wait for first step to open
+    await waitFor(() => {
+      expect(screen.getByText("Step 1")).toBeInTheDocument();
+    });
+
+    expect(screen.getByText("This is step 1")).toBeInTheDocument();
+    expect(screen.getByRole("status")).toHaveTextContent("Step 1 of 3");
+  });
+
+  it("should navigate from step 1 to step 2 when clicking Next", async () => {
+    render(<ThreeStepWalkthrough />);
+
+    // Wait for first step to open
+    await waitFor(() => {
+      expect(screen.getByText("Step 1")).toBeInTheDocument();
+    });
+
+    // Click Next button
+    const nextButton = screen.getByRole("button", { name: /next/i });
+    await user.click(nextButton);
+
+    // Wait for step 2 to open
+    await waitFor(() => {
+      expect(screen.getByText("Step 2")).toBeInTheDocument();
+    });
+
+    expect(screen.getByText("This is step 2")).toBeInTheDocument();
+    expect(screen.getByRole("status")).toHaveTextContent("Step 2 of 3");
+  });
+
+  it("should navigate from step 2 to step 3 when clicking Next", async () => {
+    render(<ThreeStepWalkthrough />);
+
+    // Wait for first step
+    await waitFor(() => {
+      expect(screen.getByText("Step 1")).toBeInTheDocument();
+    });
+
+    // Navigate to step 2
+    await user.click(screen.getByRole("button", { name: /next/i }));
+
+    await waitFor(() => {
+      expect(screen.getByText("Step 2")).toBeInTheDocument();
+    });
+
+    // Navigate to step 3
+    await user.click(screen.getByRole("button", { name: /next/i }));
+
+    // Wait for step 3 to open
+    await waitFor(() => {
+      expect(screen.getByText("Step 3")).toBeInTheDocument();
+    });
+
+    expect(screen.getByText("This is step 3")).toBeInTheDocument();
+    expect(screen.getByRole("status")).toHaveTextContent("Step 3 of 3");
+  });
+
+  it("should keep step 3 open and show Finish button", async () => {
+    render(<ThreeStepWalkthrough />);
+
+    // Navigate through all steps
+    await waitFor(() => {
+      expect(screen.getByText("Step 1")).toBeInTheDocument();
+    });
+
+    await user.click(screen.getByRole("button", { name: /next/i }));
+
+    await waitFor(() => {
+      expect(screen.getByText("Step 2")).toBeInTheDocument();
+    });
+
+    await user.click(screen.getByRole("button", { name: /next/i }));
+
+    await waitFor(() => {
+      expect(screen.getByText("Step 3")).toBeInTheDocument();
+    });
+
+    // Step 3 should remain open
+    expect(screen.getByText("This is step 3")).toBeInTheDocument();
+
+    // Finish button should be visible
+    const finishButton = screen.getByRole("button", { name: /finish/i });
+    expect(finishButton).toBeInTheDocument();
+
+    // Wait a bit to ensure it doesn't disappear
+    await new Promise((resolve) => setTimeout(resolve, 500));
+
+    expect(screen.getByText("Step 3")).toBeInTheDocument();
+    expect(screen.getByText("This is step 3")).toBeInTheDocument();
+  });
+
+  it("should call onAction with 'finish' type when Finish button is clicked", async () => {
+    const onAction = vi.fn();
+    render(<ThreeStepWalkthrough onAction={onAction} />);
+
+    // Navigate through all steps
+    await waitFor(() => {
+      expect(screen.getByText("Step 1")).toBeInTheDocument();
+    });
+
+    await user.click(screen.getByRole("button", { name: /next/i }));
+
+    await waitFor(() => {
+      expect(screen.getByText("Step 2")).toBeInTheDocument();
+    });
+
+    await user.click(screen.getByRole("button", { name: /next/i }));
+
+    await waitFor(() => {
+      expect(screen.getByText("Step 3")).toBeInTheDocument();
+    });
+
+    // Click Finish button
+    const finishButton = screen.getByRole("button", { name: /finish/i });
+    await user.click(finishButton);
+
+    // Should have called onAction with finish type
+    expect(onAction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: "finish",
+        step: 3,
+      })
+    );
+  });
+
+  it("should call onAction with 'dismiss' when close icon is clicked", async () => {
+    const onAction = vi.fn();
+    render(<ThreeStepWalkthrough onAction={onAction} />);
+
+    // Wait for first step
+    await waitFor(() => {
+      expect(screen.getByText("Step 1")).toBeInTheDocument();
+    });
+
+    // Click close button (X icon)
+    const closeButton = screen.getByLabelText(/close/i);
+    await user.click(closeButton);
+
+    // Should have called onAction with dismiss type
+    expect(onAction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: "dismiss",
+        step: 1,
+      })
+    );
+  });
+
+  it("should navigate back from step 2 to step 1", async () => {
+    render(<ThreeStepWalkthrough />);
+
+    // Navigate to step 2
+    await waitFor(() => {
+      expect(screen.getByText("Step 1")).toBeInTheDocument();
+    });
+
+    await user.click(screen.getByRole("button", { name: /next/i }));
+
+    await waitFor(() => {
+      expect(screen.getByText("Step 2")).toBeInTheDocument();
+    });
+
+    // Click Back button
+    const backButton = screen.getByRole("button", { name: /back/i });
+    await user.click(backButton);
+
+    // Should return to step 1
+    await waitFor(() => {
+      expect(screen.getByText("Step 1")).toBeInTheDocument();
+    });
+
+    expect(screen.getByText("This is step 1")).toBeInTheDocument();
+  });
+
+  it("should not show Back button on first step", async () => {
+    render(<ThreeStepWalkthrough />);
+
+    await waitFor(() => {
+      expect(screen.getByText("Step 1")).toBeInTheDocument();
+    });
+
+    // Back button should not be present
+    expect(screen.queryByRole("button", { name: /back/i })).not.toBeInTheDocument();
+  });
+
+  it("should show both Back and Next buttons on middle step", async () => {
+    render(<ThreeStepWalkthrough />);
+
+    // Navigate to step 2
+    await waitFor(() => {
+      expect(screen.getByText("Step 1")).toBeInTheDocument();
+    });
+
+    await user.click(screen.getByRole("button", { name: /next/i }));
+
+    await waitFor(() => {
+      expect(screen.getByText("Step 2")).toBeInTheDocument();
+    });
+
+    // Both buttons should be present
+    expect(screen.getByRole("button", { name: /back/i })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /next/i })).toBeInTheDocument();
+  });
+
+  it("should show Back and Finish buttons on last step", async () => {
+    render(<ThreeStepWalkthrough />);
+
+    // Navigate to step 3
+    await waitFor(() => {
+      expect(screen.getByText("Step 1")).toBeInTheDocument();
+    });
+
+    await user.click(screen.getByRole("button", { name: /next/i }));
+
+    await waitFor(() => {
+      expect(screen.getByText("Step 2")).toBeInTheDocument();
+    });
+
+    await user.click(screen.getByRole("button", { name: /next/i }));
+
+    await waitFor(() => {
+      expect(screen.getByText("Step 3")).toBeInTheDocument();
+    });
+
+    // Back and Finish buttons should be present
+    expect(screen.getByRole("button", { name: /back/i })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /finish/i })).toBeInTheDocument();
+
+    // Next button should not be present
+    expect(screen.queryByRole("button", { name: /next/i })).not.toBeInTheDocument();
+  });
+
+  it("should properly sequence through all navigation events", async () => {
+    const onAction = vi.fn();
+    render(<ThreeStepWalkthrough onAction={onAction} />);
+
+    // Step 1 -> Step 2
+    await waitFor(() => {
+      expect(screen.getByText("Step 1")).toBeInTheDocument();
+    });
+    await user.click(screen.getByRole("button", { name: /next/i }));
+
+    expect(onAction).toHaveBeenCalledWith(expect.objectContaining({ type: "next", step: 1 }));
+
+    // Step 2 -> Step 3
+    await waitFor(() => {
+      expect(screen.getByText("Step 2")).toBeInTheDocument();
+    });
+    await user.click(screen.getByRole("button", { name: /next/i }));
+
+    expect(onAction).toHaveBeenCalledWith(expect.objectContaining({ type: "next", step: 2 }));
+
+    // Step 3 -> Finish
+    await waitFor(() => {
+      expect(screen.getByText("Step 3")).toBeInTheDocument();
+    });
+    await user.click(screen.getByRole("button", { name: /finish/i }));
+
+    expect(onAction).toHaveBeenCalledWith(expect.objectContaining({ type: "finish", step: 3 }));
+
+    // Should have been called 3 times total
+    expect(onAction).toHaveBeenCalledTimes(3);
+  });
+});

package/src/popover-walkthrough.tsx

@@ -0,0 +1,45 @@
+import React, { type ReactNode } from "react";
+import * as RadixPopover from "@radix-ui/react-popover";
+
+import { PopoverInternalContext } from "./popover-internal-context";
+import { usePopoverWalkthrough } from "./usePopoverWalkthrough";
+
+export type PopoverWalkthroughProps = RadixPopover.PopoverProps & {
+  children: ReactNode;
+  step: number;
+  className?: string;
+  disableClickOutside?: boolean;
+};
+
+export const PopoverWalkthrough = ({
+  children,
+  step,
+  onOpenChange: consumerOnOpenChange,
+  disableClickOutside = true,
+  ...props
+}: PopoverWalkthroughProps) => {
+  const { actuallyOpen, onScrollStart, onScrollComplete, handleOpenChange } =
+    usePopoverWalkthrough(step);
+
+  return (
+    <RadixPopover.Root
+      open={actuallyOpen}
+      onOpenChange={(open) => handleOpenChange(open, consumerOnOpenChange)}
+      {...props}
+    >
+      <PopoverInternalContext.Provider
+        value={{
+          isOpen: actuallyOpen,
+          walkthroughStep: step,
+          onScrollStart,
+          onScrollComplete,
+          disableClickOutside,
+        }}
+      >
+        {children}
+      </PopoverInternalContext.Provider>
+    </RadixPopover.Root>
+  );
+};
+
+PopoverWalkthrough.displayName = "PopoverWalkthrough";