@purpurds/popover 0.0.1

package/src/popover-content.tsx

@@ -0,0 +1,277 @@
+import React, { forwardRef, type ReactNode, useRef } from "react";
+import { Button } from "@purpurds/button";
+import { IconClose } from "@purpurds/icon/close";
+import { Paragraph } from "@purpurds/paragraph";
+import * as RadixPopover from "@radix-ui/react-popover";
+import c from "classnames/bind";
+
+import styles from "./popover.module.scss";
+import { PopoverBack } from "./popover-back";
+import { PopoverButton } from "./popover-button";
+import { useOptionalPopoverFlow } from "./popover-flow";
+import { PopoverFooter } from "./popover-footer";
+import { PopoverHeader } from "./popover-header";
+import { PopoverNegativeContext, usePopoverInternal } from "./popover-internal-context";
+import { PopoverNext } from "./popover-next";
+
+const cx = c.bind(styles);
+
+export type PopoverAction = {
+  type: "next" | "back" | "finish" | "dismiss";
+  step?: number;
+};
+
+export type PopoverContentProps = RadixPopover.PopoverContentProps & {
+  /**
+   * Position of the arrow/beak pointing to the trigger element.
+   * Set to "none" to hide the arrow.
+   * @default "down"
+   */
+  beakPosition?: "up" | "right" | "down" | "left" | "none";
+  /**
+   * Whether to use negative (light) styling for the popover content.
+   * @default false
+   */
+  negative?: boolean;
+  /**
+   * Accessible label for the close button icon.
+   */
+  closeIconAriaLabel: string;
+  /**
+   * Main title text displayed in the popover header.
+   */
+  title: string;
+  /**
+   * Optional icon displayed in the popover header next to the title.
+   */
+  icon?: ReactNode;
+  /**
+   * Main body text content of the popover.
+   */
+  body: string;
+  /**
+   * Custom footer content. If not provided and used within PopoverFlow,
+   * default navigation buttons will be rendered.
+   */
+  children?: ReactNode;
+  /**
+   * Callback fired when user interacts with navigation buttons (next, back, finish, dismiss).
+   */
+  onAction?: (action: PopoverAction) => void;
+  /**
+   * CSS z-index value for the popover content.
+   * @default 210
+   */
+  zIndex?: number;
+};
+
+export const PopoverContent = forwardRef<HTMLDivElement, PopoverContentProps>(
+  (
+    {
+      children,
+      className,
+      beakPosition = "down",
+      align = "center",
+      alignOffset = 0,
+      sideOffset = 5, // How close or far the popover is from the trigger
+      negative = false,
+      closeIconAriaLabel,
+      title,
+      icon,
+      body,
+      onAction,
+      zIndex = 210,
+      ...props
+    },
+    ref
+  ) => {
+    const flow = useOptionalPopoverFlow();
+    const context = usePopoverInternal();
+    const headerRef = useRef<HTMLDivElement>(null);
+
+    // Map beakPosition to Radix side values
+    const beakPositionMap: Record<
+      "up" | "right" | "down" | "left" | "none",
+      "bottom" | "left" | "top" | "right"
+    > = {
+      up: "bottom",
+      right: "left",
+      down: "top",
+      left: "right",
+      none: "bottom", // Default position when no arrow
+    };
+
+    const radixSide = beakPositionMap[beakPosition];
+    const shouldShowArrow = beakPosition !== "none";
+
+    let footerContent = children;
+
+    if (flow && !children) {
+      // Use walkthroughStep from context (0 for standalone, actual step for walkthrough)
+      const currentStep = context?.walkthroughStep || flow.currentStep;
+      const isFirstStep = currentStep === 1;
+      const isLastStep = currentStep === flow.totalSteps;
+
+      footerContent = (
+        <PopoverFooter>
+          {!isFirstStep && (
+            <PopoverBack onClick={() => onAction?.({ type: "back", step: currentStep })}>
+              {flow.backLabel}
+            </PopoverBack>
+          )}
+          {isLastStep ? (
+            <PopoverButton
+              onClick={() => onAction?.({ type: "finish", step: currentStep })}
+              dismiss
+            >
+              {flow.finishLabel}
+            </PopoverButton>
+          ) : (
+            <PopoverNext onClick={() => onAction?.({ type: "next", step: currentStep })}>
+              {flow.nextLabel}
+            </PopoverNext>
+          )}
+        </PopoverFooter>
+      );
+    }
+
+    const handleOpenAutoFocus = (event: Event) => {
+      event.preventDefault();
+
+      if (flow) {
+        const contentElement = event.currentTarget as HTMLElement;
+        // Focus the content element for better accessibility
+        // Use setTimeout to ensure the DOM has fully rendered
+        setTimeout(() => {
+          contentElement.setAttribute("tabindex", "-1");
+          contentElement.focus();
+        }, 0);
+      }
+
+      props.onOpenAutoFocus?.(event);
+    };
+
+    const handleCloseAutoFocus = (event: Event) => {
+      // Prevent focus from returning to trigger in walkthrough flow
+      // This allows the next popover to manage focus properly
+      if (flow) {
+        event.preventDefault();
+      }
+
+      props.onCloseAutoFocus?.(event);
+    };
+
+    const handleClose = (event: React.MouseEvent) => {
+      const prefersReducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+      if (flow && !prefersReducedMotion) {
+        event.preventDefault();
+        setTimeout(() => {
+          onAction?.({ type: "dismiss", step: flow.currentStep });
+          flow.dismiss();
+        }, 200);
+      } else {
+        onAction?.({ type: "dismiss", step: flow?.currentStep });
+        flow?.dismiss();
+      }
+    };
+
+    const handleEscapeKey = (event: KeyboardEvent) => {
+      const prefersReducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+      if (flow && !prefersReducedMotion) {
+        event.preventDefault();
+        setTimeout(() => {
+          onAction?.({ type: "dismiss", step: flow.currentStep });
+          flow.dismiss();
+        }, 200);
+      } else {
+        onAction?.({ type: "dismiss", step: flow?.currentStep });
+        flow?.dismiss();
+      }
+    };
+
+    const handleInteractOutside = (event: Event) => {
+      if (context?.disableClickOutside) {
+        event.preventDefault();
+        return;
+      }
+
+      if (flow) {
+        const target = event.target as HTMLElement;
+        const isPopoverInteraction =
+          target.closest("[role='dialog']") ||
+          target.closest(".purpur-popover__trigger") ||
+          target.closest("button[aria-haspopup='dialog']");
+
+        if (!isPopoverInteraction) {
+          onAction?.({ type: "dismiss", step: flow.currentStep });
+          setTimeout(() => {
+            flow.dismiss();
+          }, 0);
+        }
+      }
+    };
+
+    return (
+      <RadixPopover.Portal>
+        <RadixPopover.Content
+          data-testid="popover-content"
+          role="dialog"
+          aria-modal="true"
+          aria-labelledby={props["aria-label"] ? undefined : "popover-heading"}
+          ref={ref}
+          side={radixSide}
+          sideOffset={sideOffset}
+          align={align}
+          alignOffset={alignOffset}
+          style={
+            {
+              "--popover-z-index": zIndex,
+            } as React.CSSProperties
+          }
+          className={cx(
+            "purpur-popover__content",
+            { "purpur-popover__content--negative": negative },
+            className
+          )}
+          onOpenAutoFocus={handleOpenAutoFocus}
+          onCloseAutoFocus={handleCloseAutoFocus}
+          onEscapeKeyDown={handleEscapeKey}
+          onInteractOutside={handleInteractOutside}
+          {...props}
+        >
+          <PopoverNegativeContext.Provider value={{ negative }}>
+            <div className={cx("purpur-popover__inner")}>
+              <PopoverHeader ref={headerRef} title={title} icon={icon} />
+              <Paragraph className={cx("purpur-popover__body")}>{body}</Paragraph>
+            </div>
+            {footerContent}
+
+            <RadixPopover.Close asChild onClick={handleClose}>
+              <Button
+                variant={negative ? "text" : "tertiary-purple"}
+                size="sm"
+                aria-label={closeIconAriaLabel}
+                className={cx("purpur-popover__close")}
+                negative={!negative}
+                iconOnly
+              >
+                <IconClose size="xs" className={cx("purpur-popover__icon")} />
+              </Button>
+            </RadixPopover.Close>
+          </PopoverNegativeContext.Provider>
+          {shouldShowArrow && (
+            <RadixPopover.Arrow
+              className={cx("purpur-popover__arrow")}
+              aria-hidden="true"
+              tabIndex={-1}
+            />
+          )}
+        </RadixPopover.Content>
+      </RadixPopover.Portal>
+    );
+  }
+);
+
+PopoverContent.displayName = "PopoverContent";

package/src/popover-flow.tsx

@@ -0,0 +1,170 @@
+import React, {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+} from "react";
+
+type PopoverFlowContextType = {
+  currentStep: number;
+  totalSteps: number;
+  next: () => void;
+  back: () => void;
+  dismiss: () => void;
+  registerStep: (step: number) => void;
+  unregisterStep: (step: number) => void;
+  separatorText: string;
+  stepText: string;
+  backLabel: string;
+  nextLabel: string;
+  finishLabel: string;
+  openDelay: number;
+};
+
+const PopoverFlowContext = createContext<PopoverFlowContextType | null>(null);
+
+export const usePopoverFlow = () => {
+  const context = useContext(PopoverFlowContext);
+  if (!context) {
+    throw new Error("usePopoverFlow must be used within a PopoverFlow provider");
+  }
+  return context;
+};
+
+export const useOptionalPopoverFlow = (): PopoverFlowContextType | null => {
+  return useContext(PopoverFlowContext);
+};
+
+export type PopoverFlowProps = {
+  /**
+   * Child components, typically multiple Popover components with step numbers.
+   */
+  children: ReactNode;
+  /**
+   * The step number to show when the flow starts.
+   * @default 1
+   */
+  initialStep?: number;
+  /**
+   * Callback fired when the user completes the last step of the flow.
+   */
+  onComplete?: () => void;
+  /**
+   * Callback fired when the user dismisses the flow before completing it.
+   */
+  onDismiss?: () => void;
+  /**
+   * Text used as separator in the step indicator (e.g., "of" in "1 of 3").
+   */
+  separatorText: string;
+  /**
+   * Text label for "Step" in the step indicator.
+   */
+  stepText: string;
+  /**
+   * Label for the back navigation button.
+   */
+  backLabel: string;
+  /**
+   * Label for the next navigation button.
+   */
+  nextLabel: string;
+  /**
+   * Label for the finish button on the last step.
+   */
+  finishLabel: string;
+  /**
+   * Delay in milliseconds before opening the next popover in the flow.
+   * @default 0
+   */
+  openDelay?: number;
+};
+
+export const PopoverFlow = ({
+  children,
+  initialStep = 1,
+  onComplete,
+  onDismiss,
+  separatorText,
+  stepText,
+  backLabel,
+  nextLabel,
+  finishLabel,
+  openDelay = 0,
+}: PopoverFlowProps) => {
+  const [currentStep, setCurrentStep] = useState(initialStep);
+  const [registeredSteps, setRegisteredSteps] = useState<Set<number>>(new Set());
+
+  const registerStep = useCallback((step: number) => {
+    setRegisteredSteps((prev) => {
+      const next = new Set(prev);
+      next.add(step);
+      return next;
+    });
+  }, []);
+
+  const unregisterStep = useCallback((step: number) => {
+    setRegisteredSteps((prev) => {
+      const next = new Set(prev);
+      next.delete(step);
+      return next;
+    });
+  }, []);
+
+  const next = useCallback(() => {
+    setCurrentStep((prev) => {
+      const nextStep = prev + 1;
+      if (nextStep > registeredSteps.size) {
+        onComplete?.();
+        return prev;
+      }
+      return nextStep;
+    });
+  }, [registeredSteps.size, onComplete]);
+
+  const back = useCallback(() => {
+    setCurrentStep((prev) => Math.max(1, prev - 1));
+  }, []);
+
+  const dismiss = useCallback(() => {
+    setCurrentStep(0);
+    onDismiss?.();
+  }, [onDismiss]);
+
+  const value = useMemo(
+    () => ({
+      currentStep,
+      totalSteps: registeredSteps.size,
+      next,
+      back,
+      dismiss,
+      registerStep,
+      unregisterStep,
+      separatorText,
+      stepText,
+      backLabel,
+      nextLabel,
+      finishLabel,
+      openDelay,
+    }),
+    [
+      currentStep,
+      registeredSteps.size,
+      next,
+      back,
+      dismiss,
+      registerStep,
+      unregisterStep,
+      separatorText,
+      stepText,
+      backLabel,
+      nextLabel,
+      finishLabel,
+      openDelay,
+    ]
+  );
+
+  return <PopoverFlowContext.Provider value={value}>{children}</PopoverFlowContext.Provider>;
+};

package/src/popover-footer.test.tsx

@@ -0,0 +1,21 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import { describe, expect,it } from "vitest";
+import { axe } from "vitest-axe";
+
+import { PopoverFooter } from "./popover-footer";
+
+describe("PopoverFooter", () => {
+  it("renders children", () => {
+    render(<PopoverFooter>Footer content</PopoverFooter>);
+    expect(screen.getByText("Footer content")).toBeInTheDocument();
+  });
+
+  it("should be accessible", async () => {
+    const { container } = render(<PopoverFooter>Footer content</PopoverFooter>);
+    const results = await axe(container);
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    expect(results).toHaveNoViolations();
+  });
+});

package/src/popover-footer.tsx

@@ -0,0 +1,32 @@
+import React, { type ReactNode } from "react";
+import c from "classnames/bind";
+
+import styles from "./popover.module.scss";
+import { useOptionalPopoverFlow } from "./popover-flow";
+import { PopoverSteps } from "./popover-steps";
+
+const cx = c.bind(styles);
+
+export type PopoverFooterProps = {
+  /**
+   * Footer content, typically navigation buttons like PopoverButton, PopoverNext, or PopoverBack.
+   */
+  children: ReactNode;
+  /**
+   * Optional CSS class name for custom styling.
+   */
+  className?: string;
+};
+
+export const PopoverFooter = ({ children, className }: PopoverFooterProps) => {
+  const flow = useOptionalPopoverFlow();
+
+  return (
+    <div className={cx("purpur-popover__footer", className)}>
+      {flow && <PopoverSteps />}
+      <div className={cx("purpur-popover__footer-button-group")}>{children}</div>
+    </div>
+  );
+};
+
+PopoverFooter.displayName = "PopoverFooter";

package/src/popover-header.test.tsx

@@ -0,0 +1,22 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import { describe, expect,it } from "vitest";
+import { axe } from "vitest-axe";
+
+import { PopoverHeader } from "./popover-header";
+
+describe("PopoverHeader", () => {
+  it("renders title and icon", () => {
+    render(<PopoverHeader title="Header title" icon={<span>icon</span>} />);
+    expect(screen.getByText("Header title")).toBeInTheDocument();
+    expect(screen.getByText("icon")).toBeInTheDocument();
+  });
+
+  it("should be accessible", async () => {
+    const { container } = render(<PopoverHeader title="Header title" icon={<span>icon</span>} />);
+    const results = await axe(container);
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    expect(results).toHaveNoViolations();
+  });
+});

package/src/popover-header.tsx

@@ -0,0 +1,32 @@
+import React, { forwardRef, type ReactNode } from "react";
+import { Heading } from "@purpurds/heading";
+import c from "classnames/bind";
+
+import styles from "./popover.module.scss";
+
+const cx = c.bind(styles);
+
+export type PopoverHeaderProps = {
+  title: string;
+  icon?: ReactNode;
+};
+
+export const PopoverHeader = forwardRef<HTMLDivElement, PopoverHeaderProps>(
+  ({ title, icon }, ref) => {
+    return (
+      <div ref={ref} className={cx("purpur-popover__header-content")}>
+        {icon && <span className={cx("purpur-popover__icon")}>{icon}</span>}
+        <Heading
+          tag="h2"
+          variant="title-100"
+          className={cx("purpur-popover__title")}
+          id="popover-heading"
+        >
+          {title}
+        </Heading>
+      </div>
+    );
+  }
+);
+
+PopoverHeader.displayName = "PopoverHeader";

package/src/popover-internal-context.tsx

@@ -0,0 +1,28 @@
+import { createContext, useContext } from "react";
+
+export type PopoverInternalContextValue = {
+  isOpen: boolean;
+  walkthroughStep: number;
+  onScrollComplete?: () => void;
+  onScrollStart?: () => void;
+  disableClickOutside?: boolean;
+};
+
+export const PopoverInternalContext = createContext<PopoverInternalContextValue | null>(null);
+
+export const usePopoverInternal = () => {
+  const context = useContext(PopoverInternalContext);
+  return context;
+};
+
+// Separate context for UI-specific props that are set at the Content level
+export type PopoverNegativeContextValue = {
+  negative: boolean;
+};
+
+export const PopoverNegativeContext = createContext<PopoverNegativeContextValue>({ negative: false });
+
+export const usePopoverNegative = () => {
+  const context = useContext(PopoverNegativeContext);
+  return context;
+};

package/src/popover-next.test.tsx

@@ -0,0 +1,61 @@
+import React from "react";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { axe } from "vitest-axe";
+
+import { PopoverFlow } from "./popover-flow";
+import { PopoverInternalContext } from "./popover-internal-context";
+import { PopoverNext } from "./popover-next";
+
+describe("PopoverNext", () => {
+  it("renders children and handles click", () => {
+    const onClick = vi.fn();
+    render(
+      <PopoverFlow
+        separatorText="of"
+        stepText="Step"
+        backLabel="Back"
+        nextLabel="Next"
+        finishLabel="Finish"
+      >
+        <PopoverInternalContext.Provider
+          value={{
+            isOpen: false,
+            walkthroughStep: 0,
+            negative: false,
+          }}
+        >
+          <PopoverNext onClick={onClick}>Next</PopoverNext>
+        </PopoverInternalContext.Provider>
+      </PopoverFlow>
+    );
+    fireEvent.click(screen.getByText("Next"));
+    expect(onClick).toHaveBeenCalled();
+  });
+
+  it("should be accessible", async () => {
+    const { container } = render(
+      <PopoverFlow
+        separatorText="of"
+        stepText="Step"
+        backLabel="Back"
+        nextLabel="Next"
+        finishLabel="Finish"
+      >
+        <PopoverInternalContext.Provider
+          value={{
+            isOpen: false,
+            walkthroughStep: 0,
+            negative: false,
+          }}
+        >
+          <PopoverNext>Next</PopoverNext>
+        </PopoverInternalContext.Provider>
+      </PopoverFlow>
+    );
+    const results = await axe(container);
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    expect(results).toHaveNoViolations();
+  });
+});

package/src/popover-next.tsx

@@ -0,0 +1,40 @@
+import React, { type ReactNode } from "react";
+import { Button } from "@purpurds/button";
+
+import { usePopoverFlow } from "./popover-flow";
+import { usePopoverNegative } from "./popover-internal-context";
+import { useScreenSize } from "./use-screen-size.hook";
+
+export const PopoverNext = ({
+  children,
+  onClick,
+}: {
+  children: ReactNode;
+  onClick?: () => void;
+}) => {
+  const { next } = usePopoverFlow();
+  const { negative: isNegative } = usePopoverNegative();
+  const { isMdOrSmaller } = useScreenSize();
+
+  // Invert negative: if popover is negative (light), buttons should be normal (dark)
+  const negative = isNegative ? false : true;
+
+  const handleClick = () => {
+    onClick?.();
+    next();
+  };
+
+  return (
+    <Button
+      size="sm"
+      variant="primary"
+      onClick={handleClick}
+      negative={negative}
+      fullWidth={isMdOrSmaller}
+    >
+      {children}
+    </Button>
+  );
+};
+
+PopoverNext.displayName = "PopoverNext";