@purpurds/popover 0.0.1

package/src/popover.tsx

@@ -0,0 +1,76 @@
+import React, { type ReactNode } from "react";
+import type * as RadixPopover from "@radix-ui/react-popover";
+
+import { PopoverBack } from "./popover-back";
+import { PopoverButton } from "./popover-button";
+import { type PopoverAction,PopoverContent } from "./popover-content";
+import { PopoverFlow } from "./popover-flow";
+import { PopoverFooter } from "./popover-footer";
+import { PopoverNext } from "./popover-next";
+import { PopoverStandalone } from "./popover-standalone";
+import { PopoverTrigger } from "./popover-trigger";
+import { PopoverWalkthrough } from "./popover-walkthrough";
+
+export type { PopoverAction };
+
+// Base props shared by both variants
+type BasePopoverProps = RadixPopover.PopoverProps & {
+  children: ReactNode;
+  className?: string;
+};
+
+// Standalone variant props
+type StandalonePopoverProps = BasePopoverProps & {
+  multistep?: false;
+  step?: never;
+  disableClickOutside?: boolean;
+};
+
+// Walkthrough variant props
+type WalkthroughPopoverProps = BasePopoverProps & {
+  multistep: true;
+  step: number;
+  disableClickOutside?: boolean;
+};
+
+export type PopoverProps = StandalonePopoverProps | WalkthroughPopoverProps;
+
+type PopoverCmp<P> = React.FunctionComponent<P> & {
+  Back: typeof PopoverBack;
+  Button: typeof PopoverButton;
+  Content: typeof PopoverContent;
+  Flow: typeof PopoverFlow;
+  Footer: typeof PopoverFooter;
+  Next: typeof PopoverNext;
+  Trigger: typeof PopoverTrigger;
+};
+
+export const Popover: PopoverCmp<PopoverProps> = (props) => {
+  const { multistep = false, disableClickOutside, ...restProps } = props;
+
+  if (multistep) {
+    return (
+      <PopoverWalkthrough
+        {...(restProps as WalkthroughPopoverProps)}
+        disableClickOutside={disableClickOutside ?? true}
+      />
+    );
+  }
+
+  return (
+    <PopoverStandalone
+      {...(restProps as StandalonePopoverProps)}
+      disableClickOutside={disableClickOutside}
+    />
+  );
+};
+
+Popover.Back = PopoverBack;
+Popover.Button = PopoverButton;
+Popover.Content = PopoverContent;
+Popover.Flow = PopoverFlow;
+Popover.Footer = PopoverFooter;
+Popover.Next = PopoverNext;
+Popover.Trigger = PopoverTrigger;
+
+Popover.displayName = "Popover";

package/src/use-screen-size.hook.ts

@@ -0,0 +1,39 @@
+import { useCallback, useEffect, useState } from "react";
+import { purpurBreakpointMd } from "@purpurds/tokens";
+
+const DEBOUNCE_DELAY = 150;
+
+export const SCREEN_MEDIA_QUERY = {
+  MAX_MD: `(max-width: ${purpurBreakpointMd})`,
+} as const;
+
+export const useScreenSize = () => {
+  const maxMediumScreen = window.matchMedia(SCREEN_MEDIA_QUERY.MAX_MD);
+  function updateSize() {
+    setIsMdOrSmaller(maxMediumScreen.matches);
+  }
+
+  const [isMdOrSmaller, setIsMdOrSmaller] = useState(() => {
+    if (typeof window === "undefined") return false;
+    return window.matchMedia(SCREEN_MEDIA_QUERY.MAX_MD).matches;
+  });
+
+  const handleResize = useCallback(() => {
+    let timeoutId: number;
+
+    return () => {
+      clearTimeout(timeoutId);
+      timeoutId = setTimeout(() => updateSize(), DEBOUNCE_DELAY);
+    };
+  }, [updateSize]);
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+
+    window.addEventListener("resize", handleResize);
+
+    return () => window.removeEventListener("resize", handleResize);
+  }, [handleResize]);
+
+  return { isMdOrSmaller };
+};

package/src/use-smooth-scroll.ts

@@ -0,0 +1,62 @@
+import { useCallback, useRef } from "react";
+
+export const useSmoothScroll = (onComplete?: () => void) => {
+  const scrollAnimationId = useRef<number | null>(null);
+
+  const cancelScroll = useCallback(() => {
+    if (scrollAnimationId.current) {
+      cancelAnimationFrame(scrollAnimationId.current);
+      scrollAnimationId.current = null;
+    }
+  }, []);
+
+  const scrollToElement = useCallback(
+    (element: HTMLElement, duration: number = 600) => {
+      const prefersReducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+      const rect = element.getBoundingClientRect();
+      const absoluteTop = rect.top + window.pageYOffset;
+      const elementHeight = rect.height;
+      const viewportHeight = window.innerHeight;
+
+      let targetY = absoluteTop - viewportHeight / 2 + elementHeight / 2;
+      const documentHeight = document.documentElement.scrollHeight;
+      const maxScroll = Math.max(0, documentHeight - viewportHeight);
+      targetY = Math.max(0, Math.min(targetY, maxScroll));
+
+      if (prefersReducedMotion) {
+        window.scrollTo(0, targetY);
+        onComplete?.();
+        return;
+      }
+
+      const startY = window.pageYOffset;
+      const distance = targetY - startY;
+      const startTime = performance.now();
+
+      const animateScroll = (currentTime: number) => {
+        const elapsed = currentTime - startTime;
+        const progress = Math.min(elapsed / duration, 1);
+
+        const easeInOut =
+          progress < 0.5 ? 2 * progress * progress : 1 - Math.pow(-2 * progress + 2, 2) / 2;
+
+        const currentY = startY + distance * easeInOut;
+        window.scrollTo(0, currentY);
+
+        if (progress < 1) {
+          scrollAnimationId.current = requestAnimationFrame(animateScroll);
+        } else {
+          scrollAnimationId.current = null;
+          onComplete?.();
+        }
+      };
+
+      cancelScroll();
+
+      scrollAnimationId.current = requestAnimationFrame(animateScroll);
+    },
+    [onComplete, cancelScroll]
+  );
+
+  return { scrollToElement, cancelScroll };
+};

package/src/usePopoverTrigger.ts

@@ -0,0 +1,59 @@
+import { useEffect, useRef } from "react";
+
+import { useOptionalPopoverFlow } from "./popover-flow";
+import { usePopoverInternal } from "./popover-internal-context";
+import { useSmoothScroll } from "./use-smooth-scroll";
+
+export function usePopoverTrigger(ref: React.Ref<HTMLButtonElement>) {
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const context = usePopoverInternal();
+  const flow = useOptionalPopoverFlow();
+  const hasScrolled = useRef(false);
+  const { scrollToElement, cancelScroll } = useSmoothScroll(context?.onScrollComplete);
+
+  // Forward ref
+  useEffect(() => {
+    if (typeof ref === "function") {
+      ref(triggerRef.current);
+    } else if (ref) {
+      (ref as React.MutableRefObject<HTMLButtonElement | null>).current = triggerRef.current;
+    }
+  }, [ref]);
+
+  // Walkthrough scroll logic
+  useEffect(() => {
+    const isActiveStep =
+      flow &&
+      context?.walkthroughStep !== undefined &&
+      flow.currentStep === context.walkthroughStep &&
+      triggerRef.current &&
+      !hasScrolled.current;
+
+    if (isActiveStep) {
+      const element = triggerRef.current!;
+      const rect = element.getBoundingClientRect();
+      const buffer = 100;
+      const isVisible =
+        rect.top >= -buffer &&
+        rect.bottom <= window.innerHeight + buffer &&
+        rect.left >= -buffer &&
+        rect.right <= window.innerWidth + buffer;
+
+      if (isVisible) {
+        context?.onScrollComplete?.();
+      } else {
+        context?.onScrollStart?.();
+        scrollToElement(element);
+      }
+      hasScrolled.current = true;
+    } else if (flow?.currentStep !== context?.walkthroughStep) {
+      hasScrolled.current = false;
+      cancelScroll();
+    }
+  }, [flow?.currentStep, context?.walkthroughStep, flow, scrollToElement, cancelScroll, context]);
+
+  // Cancel scroll on unmount
+  useEffect(() => cancelScroll, [cancelScroll]);
+
+  return { triggerRef, context };
+}

package/src/usePopoverWalkthrough.ts

@@ -0,0 +1,85 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { useOptionalPopoverFlow } from "./popover-flow";
+
+export function usePopoverWalkthrough(step: number) {
+  const flow = useOptionalPopoverFlow();
+  const [actuallyOpen, setActuallyOpen] = useState(false);
+  const [waitingForScroll, setWaitingForScroll] = useState(false);
+  const timeoutRef = useRef<number | null>(null);
+  const openedAtRef = useRef<number>(0);
+
+  useEffect(() => {
+    if (flow) {
+      flow.registerStep(step);
+      return () => flow.unregisterStep(step);
+    }
+    return () => {};
+  }, [flow, step]);
+
+  const shouldBeOpen = flow?.currentStep === step;
+
+  const onScrollStart = useCallback(() => {
+    setWaitingForScroll(true);
+  }, []);
+
+  const onScrollComplete = useCallback(() => {
+    setWaitingForScroll(false);
+    if (shouldBeOpen) {
+      const delay = flow.openDelay;
+      timeoutRef.current = window.setTimeout(() => {
+        setActuallyOpen(true);
+        openedAtRef.current = Date.now();
+      }, delay);
+    }
+  }, [shouldBeOpen, flow]);
+
+  useEffect(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+
+    if (shouldBeOpen) {
+      if (!waitingForScroll) {
+        const delay = flow.openDelay;
+        timeoutRef.current = window.setTimeout(() => {
+          setActuallyOpen(true);
+          openedAtRef.current = Date.now();
+        }, delay);
+      }
+    } else {
+      setActuallyOpen(false);
+      setWaitingForScroll(false);
+      openedAtRef.current = 0;
+    }
+
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+        timeoutRef.current = null;
+      }
+    };
+  }, [shouldBeOpen, waitingForScroll, flow]);
+
+  const handleOpenChange = useCallback(
+    (open: boolean, consumerOnOpenChange?: (open: boolean) => void) => {
+      consumerOnOpenChange?.(open);
+      if (!open && actuallyOpen && flow && flow.currentStep === step) {
+        const timeSinceOpen = Date.now() - openedAtRef.current;
+        if (timeSinceOpen < 10 || timeoutRef.current !== null) {
+          return;
+        }
+        flow.dismiss();
+      }
+    },
+    [actuallyOpen, flow, step]
+  );
+
+  return {
+    actuallyOpen,
+    onScrollStart,
+    onScrollComplete,
+    handleOpenChange,
+  };
+}

package/vitest.setup.ts

@@ -0,0 +1,30 @@
+import * as matchers from "@testing-library/jest-dom/matchers";
+import { expect, vi } from "vitest";
+import * as axeMatchers from "vitest-axe/matchers";
+
+import "vitest-canvas-mock";
+import "vitest-axe/extend-expect";
+
+expect.extend(matchers);
+expect.extend(axeMatchers);
+
+const matchMedia = vi.fn(function (query) {
+  return {
+    matches: true,
+    media: query,
+    onchange: null,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+  };
+});
+
+vi.stubGlobal("matchMedia", matchMedia);
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const ResizeObserverMock = vi.fn(function (this: any) {
+  this.disconnect = vi.fn();
+  this.observe = vi.fn();
+  this.takeRecords = vi.fn();
+  this.unobserve = vi.fn();
+});
+vi.stubGlobal("ResizeObserver", ResizeObserverMock);