@purpurds/popover 0.0.1

package/src/popover.stories.tsx

@@ -0,0 +1,1157 @@
+import React from "react";
+import { Button } from "@purpurds/button";
+import { Heading } from "@purpurds/heading";
+import { IconHeart } from "@purpurds/icon/heart";
+import { IconInfo } from "@purpurds/icon/info";
+import { Link } from "@purpurds/link";
+import { Paragraph } from "@purpurds/paragraph";
+import { type Meta, type StoryObj } from "@storybook/react";
+
+import "@purpurds/link/styles";
+import "@purpurds/icon/styles";
+import "@purpurds/button/styles";
+import "@purpurds/heading/styles";
+import "@purpurds/paragraph/styles";
+import { Popover, type PopoverAction } from "./popover";
+
+const meta: Meta<typeof Popover> = {
+  title: "Dialogs and Overlays/Popover",
+  component: Popover,
+  subcomponents: {
+    "Popover.Trigger": Popover.Trigger,
+    "Popover.Content": Popover.Content,
+    "Popover.Footer": Popover.Footer,
+    "Popover.Button": Popover.Button,
+    "Popover.Flow": Popover.Flow,
+  },
+  parameters: {
+    layout: "centered",
+    docs: {
+      description: {
+        component: `
+## Popover
+
+Popovers help users discover new features and important changes in the UI, enhancing the user experience and driving adoption of high-value features.
+
+**Built on [Radix Popover](https://www.radix-ui.com/primitives/docs/components/popover) for accessibility and positioning.**
+
+**Usage guidelines:**
+- Prefer single-step popovers for clarity. If a walkthrough is needed, keep it to 3–5 steps maximum and follow the user's natural workflow order.
+- Use popovers for features with high business value or those that create new value for users, not just minor improvements.
+- Consider user segmentation and avoid conflicting or redundant messages. Bundle related highlights when possible.
+
+[See Figma design](https://www.figma.com/design/XEaIIFskrrxIBHMZDkIuIg/Purpur-DS---Components-and-guidelines?node-id=43484-6510&p=f&m=dev)
+        `,
+      },
+    },
+    design: [
+      {
+        name: "Popover",
+        type: "figma",
+        url: "https://www.figma.com/design/XEaIIFskrrxIBHMZDkIuIg/Purpur-DS---Components-and-guidelines?node-id=43484-6510&p=f&m=dev",
+      },
+    ],
+  },
+  argTypes: {
+    open: {
+      control: "boolean",
+      description: "Controls whether the popover is open",
+    },
+  },
+};
+
+export default meta;
+
+interface StandaloneArgs {
+  negative: boolean;
+  beakPosition: "up" | "right" | "down" | "left" | "none";
+  align: "start" | "center" | "end";
+  closeIconAriaLabel: string;
+  headerTitle: string;
+  headerIcon: boolean;
+  body: string;
+  showFooter: boolean;
+  button: boolean;
+  buttonText: string;
+  highlight: boolean;
+}
+
+interface WalkthroughArgs {
+  separatorText: string;
+  stepText: string;
+  backLabel: string;
+  nextLabel: string;
+  finishLabel: string;
+  closeIconAriaLabel: string;
+  step1BeakPosition: "up" | "right" | "down" | "left" | "none";
+  step2BeakPosition: "up" | "right" | "down" | "left" | "none";
+  step3BeakPosition: "up" | "right" | "down" | "left" | "none";
+  step4BeakPosition: "up" | "right" | "down" | "left" | "none";
+  avoidCollisions: boolean;
+  step1Body: string;
+  step2Body: string;
+  step3Body: string;
+  step4Body: string;
+}
+
+/**
+ * Standalone
+ *
+ * A popover highlights new features or significant changes in existing ones. Content may link to help articles or telia.se/foretag pages. Triggered by user action or appearing on a new or updated page, it's a single callout with no subsequent steps, designed for onboarding users to new or improved features/flows.
+ *
+ * Use cases: Introducing a feature, highlighting significant changes, prompting user action.
+ *
+ * Props:
+ * - Built on Radix Popover for accessibility and positioning.
+ * - `title` (required): string — header title text.
+ * - `icon` (optional): ReactNode — optional header icon.
+ * - `body` (required): string — main content.
+ * - `beakPosition`, `align`, `showArrow` (optional): Placement and appearance.
+ * - `negative`, `highlight` (optional): Visual variants.
+ * - `closeIconAriaLabel` (required for accessibility): Label for close icon.
+ * - All other [Radix Popover props](https://www.radix-ui.com/primitives/docs/components/popover#root) are supported.
+ *
+ * Note: Story args like `headerTitle`, `headerIcon`, `buttonText`, etc. are for Storybook controls only and are mapped to the actual component props in the render function.
+ */
+export const Standalone: StoryObj = {
+  args: {
+    negative: false,
+    beakPosition: "down",
+    align: "center",
+    closeIconAriaLabel: "Close",
+    headerTitle: "This is a title",
+    headerIcon: true,
+    body: "Body text lorem ipsum dolor sit amet, consectetur adipiscing elit.",
+    showFooter: true,
+    button: false,
+    buttonText: "Got it",
+    highlight: false,
+  },
+  argTypes: {
+    negative: {
+      control: "boolean",
+      description: "Use negative (light) variant",
+    },
+    beakPosition: {
+      control: "select",
+      options: ["up", "right", "down", "left", "none"],
+      description:
+        "Position of the popover beak/arrow (up, right, down, left). Use none to hide the arrow.",
+    },
+    align: {
+      control: "select",
+      options: ["start", "center", "end"],
+      description: "Alignment of the popover",
+    },
+    closeIconAriaLabel: {
+      control: "text",
+      description: "Accessible label for close icon",
+    },
+    headerTitle: {
+      control: "text",
+      description: "Title text (required prop in component, mapped from this control)",
+    },
+    headerIcon: {
+      control: "boolean",
+      description: "Show header icon (optional icon prop in component)",
+    },
+    body: {
+      control: "text",
+      description: "Body text content",
+    },
+    showFooter: {
+      control: "boolean",
+      description: "Show footer with button",
+    },
+    button: {
+      control: "boolean",
+      description: "Use button as trigger",
+    },
+    buttonText: {
+      control: "text",
+      description: "Footer button text",
+    },
+    highlight: {
+      control: "boolean",
+      description: "Highlight the trigger",
+    },
+  },
+  render: (args) => {
+    const typedArgs = args as unknown as StandaloneArgs;
+    const backgroundColor = typedArgs.negative
+      ? "var(--purpur-color-background-tone-on-tone-primary)"
+      : "transparent";
+
+    return (
+      <div
+        style={{
+          padding: "50px",
+          backgroundColor,
+          minHeight: "450px",
+          minWidth: "450px",
+          display: "flex",
+          placeContent: "center",
+          alignItems: "center",
+        }}
+      >
+        <Popover>
+          <Popover.Trigger highlight={typedArgs.highlight}>
+            {typedArgs.button ? (
+              <Button variant="primary">{typedArgs.buttonText}</Button>
+            ) : (
+              <Button variant="primary" aria-label={typedArgs.buttonText} iconOnly>
+                <IconInfo />
+              </Button>
+            )}
+          </Popover.Trigger>
+          <Popover.Content
+            negative={typedArgs.negative}
+            beakPosition={typedArgs.beakPosition}
+            align={typedArgs.align}
+            closeIconAriaLabel={typedArgs.closeIconAriaLabel}
+            title={typedArgs.headerTitle || "Default Title"}
+            {...(typedArgs.headerIcon && { icon: <IconHeart size="sm" /> })}
+            body={typedArgs.body}
+            onAction={(action: PopoverAction) => console.log("Popover action:", action)}
+          >
+            {typedArgs.showFooter && (
+              <Popover.Footer>
+                <Popover.Button onClick={() => console.log("Popover dismissed")}>
+                  {typedArgs.buttonText}
+                </Popover.Button>
+              </Popover.Footer>
+            )}
+          </Popover.Content>
+        </Popover>
+      </div>
+    );
+  },
+};
+
+/**
+ * User Initiated Walkthrough
+ *
+ * A walkthrough is an interactive tour guiding users through a series of hands-on steps. It effectively introduces new features within a single page, a sequence of steps across multiple pages, or highlights a feature's immediate business value.
+ *
+ * All popovers in a walkthrough must be wrapped under a single `PopoverFlow` component to ensure correct step management and navigation.
+ *
+ * Use cases: Onboarding users to a new workflow, providing a tour of new features, or offering contextual assistance during MyBusiness configuration.
+ *
+ * Props (for the Popover component):
+ * - Built on Radix Popover for accessibility and positioning.
+ * - `multistep` (required): true
+ * - `step` (required): number — the step index for this popover in the walkthrough. Steps must be sequential (e.g., 1, 2, 3, ...).
+ * - `initialStep` (optional): number — sets which step is open when the walkthrough mounts. If set to 0, the walkthrough starts closed and no step is shown initially.
+ * - `title` (required): string — header title text.
+ * - `icon` (optional): ReactNode — optional header icon.
+ * - `body` (required): string — main content.
+ * - `side`, `align`, `showArrow` (optional): Placement and appearance.
+ * - `negative`, `highlight` (optional): Visual variants.
+ * - `closeIconAriaLabel` (required for accessibility): Label for close icon.
+ * - All other [Radix Popover props](https://www.radix-ui.com/primitives/docs/components/popover#root) are supported.
+ *
+ * Note: Story args like `separatorText`, `stepText`, `backLabel`, `nextLabel`, `finishLabel`, etc. are for Storybook controls only and are mapped to the actual component props in the render function or via the PopoverFlow provider.
+ */
+export const UserInitiatedWalkthrough: StoryObj = {
+  args: {
+    separatorText: "of",
+    stepText: "Step",
+    backLabel: "Back",
+    nextLabel: "Next",
+    finishLabel: "Finish",
+    closeIconAriaLabel: "Exit tour",
+    openDelay: 0,
+  },
+  argTypes: {
+    separatorText: {
+      control: "text",
+      description: "Separator text between step numbers",
+    },
+    stepText: {
+      control: "text",
+      description: "Label for 'Step'",
+    },
+    backLabel: {
+      control: "text",
+      description: "Label for back button",
+    },
+    nextLabel: {
+      control: "text",
+      description: "Label for next button",
+    },
+    finishLabel: {
+      control: "text",
+      description: "Label for finish button",
+    },
+    closeIconAriaLabel: {
+      control: "text",
+      description: "Accessible label for close icon",
+    },
+    openDelay: {
+      control: "number",
+      description: "Delay in milliseconds before opening the popover",
+    },
+  },
+  render: function UserInitiatedWalkthroughStory(args) {
+    const typedArgs = args as unknown as {
+      separatorText: string;
+      stepText: string;
+      backLabel: string;
+      nextLabel: string;
+      finishLabel: string;
+      closeIconAriaLabel: string;
+      openDelay: number;
+    };
+
+    const [walkthroughStarted, setWalkthroughStarted] = React.useState(false);
+    const [walkthroughCompleted, setWalkthroughCompleted] = React.useState(false);
+    const startButtonRef = React.useRef<HTMLButtonElement>(null);
+
+    const handleStartWalkthrough = () => {
+      setWalkthroughStarted(true);
+      setWalkthroughCompleted(false);
+    };
+
+    const handleAction = (action: PopoverAction) => {
+      console.log("Walkthrough action:", action);
+
+      if (action.type === "finish" || action.type === "dismiss") {
+        setWalkthroughCompleted(true);
+        setWalkthroughStarted(false);
+
+        // Return focus to the start button
+        setTimeout(() => {
+          startButtonRef.current?.focus();
+          console.log("Focus returned to start button");
+        }, 100);
+
+        if (action.type === "finish") {
+          console.log("Walkthrough completed successfully");
+        } else {
+          console.log("Walkthrough dismissed");
+        }
+      }
+    };
+
+    return (
+      <div
+        style={{
+          minHeight: "600px",
+          position: "relative",
+          padding: "40px",
+        }}
+      >
+        {/* Header with Start Button */}
+        <div
+          style={{
+            display: "flex",
+            flexDirection: "column",
+            alignItems: "center",
+            gap: "16px",
+            marginBottom: "40px",
+            paddingBottom: "20px",
+            borderBottom: "1px solid var(--purpur-color-border-secondary)",
+          }}
+        >
+          <Heading tag="h2">User-Initiated Walkthrough Demo</Heading>
+          <p style={{ textAlign: "center", maxWidth: "500px" }}>
+            This demonstrates a walkthrough that starts when the user clicks the button below. After
+            completion or dismissal, focus returns to the start button.
+          </p>
+          <Button
+            ref={startButtonRef}
+            variant="primary"
+            onClick={handleStartWalkthrough}
+            disabled={walkthroughStarted}
+          >
+            {walkthroughStarted ? "Tour in Progress..." : "Start Product Tour"}
+          </Button>
+          {walkthroughCompleted && (
+            <div
+              style={{
+                backgroundColor: "var(--purpur-color-background-tone-success)",
+                color: "var(--purpur-color-text-on-color)",
+                padding: "12px 24px",
+                borderRadius: "4px",
+                fontSize: "14px",
+              }}
+            >
+              ✅ Tour completed! Focus has returned to the start button.
+            </div>
+          )}
+        </div>
+
+        {/* Main Content Area - Always Visible */}
+        <div
+          style={{
+            position: "relative",
+            minHeight: "400px",
+            backgroundColor: "var(--purpur-color-background-surface)",
+            borderRadius: "8px",
+            padding: "20px",
+          }}
+        >
+          {walkthroughStarted && (
+            <Popover.Flow
+              separatorText={typedArgs.separatorText}
+              stepText={typedArgs.stepText}
+              backLabel={typedArgs.backLabel}
+              nextLabel={typedArgs.nextLabel}
+              finishLabel={typedArgs.finishLabel}
+              openDelay={typedArgs.openDelay}
+            >
+              {/* Step 1 - Top Left */}
+              <div style={{ position: "absolute", top: "40px", left: "40px" }}>
+                <Popover multistep step={1}>
+                  <Popover.Trigger>
+                    <Button variant="primary" iconOnly>
+                      <IconHeart />
+                    </Button>
+                  </Popover.Trigger>
+                  <Popover.Content
+                    beakPosition="down"
+                    closeIconAriaLabel={typedArgs.closeIconAriaLabel}
+                    title="Welcome to the Tour"
+                    icon={<IconHeart size="sm" />}
+                    body="Let's explore the main features of this application. Click Next to continue."
+                    onAction={handleAction}
+                  />
+                </Popover>
+              </div>
+
+              {/* Step 2 - Top Right */}
+              <div style={{ position: "absolute", top: "40px", right: "40px" }}>
+                <Popover multistep step={2}>
+                  <Popover.Trigger>
+                    <Button variant="primary">Settings</Button>
+                  </Popover.Trigger>
+                  <Popover.Content
+                    beakPosition="down"
+                    align="end"
+                    closeIconAriaLabel={typedArgs.closeIconAriaLabel}
+                    title="Customize Your Experience"
+                    body="Access your settings and preferences here. You can customize themes, notifications, and more."
+                    onAction={handleAction}
+                  />
+                </Popover>
+              </div>
+
+              {/* Step 3 - Center */}
+              <div
+                style={{
+                  position: "absolute",
+                  top: "50%",
+                  left: "50%",
+                  transform: "translate(-50%, -50%)",
+                }}
+              >
+                <div
+                  style={{
+                    padding: "40px",
+                    backgroundColor: "var(--purpur-color-background-base)",
+                    borderRadius: "8px",
+                    textAlign: "center",
+                    boxShadow: "0 2px 8px rgba(0,0,0,0.1)",
+                  }}
+                >
+                  <Heading tag="h3" style={{ marginBottom: "16px" }}>
+                    Main Content Area
+                  </Heading>
+                  <Popover multistep step={3}>
+                    <Popover.Trigger>
+                      <Button variant="primary">Get Started</Button>
+                    </Popover.Trigger>
+                    <Popover.Content
+                      beakPosition="up"
+                      closeIconAriaLabel={typedArgs.closeIconAriaLabel}
+                      title="Ready to Begin!"
+                      body="This is where you'll spend most of your time. Click Complete to finish the tour and return focus to the start button."
+                      onAction={handleAction}
+                    />
+                  </Popover>
+                </div>
+              </div>
+            </Popover.Flow>
+          )}
+
+          {/* Static elements when walkthrough is not active */}
+          {!walkthroughStarted && (
+            <>
+              <div style={{ position: "absolute", top: "40px", left: "40px" }}>
+                <Button variant="primary" iconOnly disabled>
+                  <IconHeart />
+                </Button>
+              </div>
+              <div style={{ position: "absolute", top: "40px", right: "40px" }}>
+                <Button variant="primary" disabled>
+                  Settings
+                </Button>
+              </div>
+              <div
+                style={{
+                  position: "absolute",
+                  top: "50%",
+                  left: "50%",
+                  transform: "translate(-50%, -50%)",
+                  padding: "40px",
+                  backgroundColor: "var(--purpur-color-background-base)",
+                  borderRadius: "8px",
+                  textAlign: "center",
+                  boxShadow: "0 2px 8px rgba(0,0,0,0.1)",
+                }}
+              >
+                <Heading tag="h3" style={{ marginBottom: "16px" }}>
+                  Main Content Area
+                </Heading>
+                <Button variant="primary" disabled>
+                  Get Started
+                </Button>
+              </div>
+            </>
+          )}
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Walkthrough: StoryObj = {
+  parameters: {
+    docs: { disable: true },
+  },
+  args: {
+    separatorText: "of",
+    stepText: "Step",
+    backLabel: "Back",
+    nextLabel: "Next",
+    finishLabel: "Finish",
+    closeIconAriaLabel: "Close",
+    step1BeakPosition: "down",
+    step2BeakPosition: "down",
+    step3BeakPosition: "up",
+    step4BeakPosition: "down",
+    avoidCollisions: false,
+    step1Body: "Start here in the top left corner. This is the first step.",
+    step2Body: "Continue here in the top right corner. This is the second step.",
+    step3Body: "Now we're at the bottom of the page. This is the third step.",
+    step4Body: "Finish here in the middle. You are done!",
+  },
+  argTypes: {
+    separatorText: {
+      control: "text",
+      description: "Separator text between step numbers",
+    },
+    stepText: {
+      control: "text",
+      description: "Label for 'Step'",
+    },
+    backLabel: {
+      control: "text",
+      description: "Label for back button",
+    },
+    nextLabel: {
+      control: "text",
+      description: "Label for next button",
+    },
+    finishLabel: {
+      control: "text",
+      description: "Label for finish button",
+    },
+    closeIconAriaLabel: {
+      control: "text",
+      description: "Accessible label for close icon",
+    },
+    step1BeakPosition: {
+      control: "select",
+      options: ["up", "right", "down", "left", "none"],
+      description: "Beak position for step 1",
+    },
+    step2BeakPosition: {
+      control: "select",
+      options: ["up", "right", "down", "left", "none"],
+      description: "Beak position for step 2",
+    },
+    step3BeakPosition: {
+      control: "select",
+      options: ["up", "right", "down", "left", "none"],
+      description: "Beak position for step 3",
+    },
+    step4BeakPosition: {
+      control: "select",
+      options: ["up", "right", "down", "left", "none"],
+      description: "Beak position for step 4",
+    },
+    avoidCollisions: {
+      control: "boolean",
+      description: "Avoid collisions with viewport edges",
+    },
+    step1Body: {
+      control: "text",
+      description: "Body text for step 1",
+    },
+    step2Body: {
+      control: "text",
+      description: "Body text for step 2",
+    },
+    step3Body: {
+      control: "text",
+      description: "Body text for step 3",
+    },
+    step4Body: {
+      control: "text",
+      description: "Body text for step 4",
+    },
+  },
+  render: function WalkthroughStory(args) {
+    const typedArgs = args as unknown as WalkthroughArgs;
+    const [key, setKey] = React.useState(0);
+    const [showAutoStartMessage, setShowAutoStartMessage] = React.useState(true);
+    const [walkthroughCompleted, setWalkthroughCompleted] = React.useState(false);
+
+    const handleAction = (action: PopoverAction) => {
+      console.log("Popover action:", action);
+
+      // Handle different completion scenarios
+      if (action.type === "finish") {
+        console.log("Walkthrough completed successfully!");
+        setShowAutoStartMessage(false);
+        setWalkthroughCompleted(true);
+
+        // Example: Consumer can decide what to do here
+        // - Redirect to a specific page
+        // - Focus on a specific element
+        // - Save user preference to not show again
+        // - Enable certain features
+        // window.location.href = '/dashboard';
+        // document.querySelector('#main-feature')?.focus();
+      } else if (action.type === "dismiss") {
+        console.log("Walkthrough dismissed by user");
+        setShowAutoStartMessage(false);
+
+        // Example: Different behavior for dismiss
+        // - Maybe show a "resume tour" option
+        // - Track analytics that user skipped
+        // - Show a less intrusive hint later
+      }
+    };
+
+    return (
+      <div
+        style={{
+          width: "100vw",
+          height: "250vh",
+          position: "relative",
+        }}
+      >
+        {showAutoStartMessage && (
+          <div
+            style={{
+              position: "fixed",
+              top: "20px",
+              left: "50%",
+              transform: "translateX(-50%)",
+              backgroundColor: "var(--purpur-color-background-tone-info)",
+              color: "var(--purpur-color-text-on-color)",
+              padding: "12px 24px",
+              borderRadius: "4px",
+              zIndex: 1000,
+              fontSize: "14px",
+            }}
+          >
+            🎉 Welcome! We&apos;ve added new features. Let&apos;s take a quick tour.
+          </div>
+        )}
+
+        {walkthroughCompleted && (
+          <div
+            style={{
+              position: "fixed",
+              top: "20px",
+              left: "50%",
+              transform: "translateX(-50%)",
+              backgroundColor: "var(--purpur-color-background-tone-success)",
+              color: "var(--purpur-color-text-on-color)",
+              padding: "12px 24px",
+              borderRadius: "4px",
+              zIndex: 1000,
+              fontSize: "14px",
+            }}
+          >
+            ✅ Tour completed! You can now explore the new features.
+          </div>
+        )}
+
+        <div
+          style={{
+            paddingTop: "60px",
+            display: "flex",
+            justifyContent: "center",
+          }}
+        >
+          <Button
+            variant="primary"
+            onClick={() => {
+              setKey((prev) => prev + 1);
+              setShowAutoStartMessage(true);
+              setWalkthroughCompleted(false);
+            }}
+          >
+            Restart Walkthrough
+          </Button>
+        </div>
+
+        <Popover.Flow
+          key={key}
+          separatorText={typedArgs.separatorText}
+          stepText={typedArgs.stepText}
+          backLabel={typedArgs.backLabel}
+          nextLabel={typedArgs.nextLabel}
+          finishLabel={typedArgs.finishLabel}
+        >
+          {/* Step 1 - Top Left - New Dashboard Widget */}
+          <div style={{ position: "absolute", top: "150px", left: "100px" }}>
+            <div
+              style={{
+                border: "2px dashed var(--purpur-color-border-primary)",
+                padding: "20px",
+                borderRadius: "8px",
+                background: "var(--purpur-color-background-surface)",
+              }}
+            >
+              <Heading tag="h3" style={{ marginBottom: "8px" }}>
+                📊 Analytics Widget
+              </Heading>
+              <p style={{ color: "var(--purpur-color-text-secondary)" }}>New feature!</p>
+              <Popover multistep step={1}>
+                <Popover.Trigger>
+                  <Button variant="primary" size="sm">
+                    View Analytics
+                  </Button>
+                </Popover.Trigger>
+                <Popover.Content
+                  beakPosition={typedArgs.step1BeakPosition}
+                  avoidCollisions={typedArgs.avoidCollisions}
+                  closeIconAriaLabel={typedArgs.closeIconAriaLabel}
+                  title="New: Analytics Dashboard"
+                  body="Track your performance with our new analytics widget. View real-time data and insights."
+                  onAction={handleAction}
+                />
+              </Popover>
+            </div>
+          </div>
+
+          {/* Step 2 - Top Right - Quick Actions */}
+          <div style={{ position: "absolute", top: "150px", right: "100px" }}>
+            <div
+              style={{
+                border: "2px dashed var(--purpur-color-border-primary)",
+                padding: "20px",
+                borderRadius: "8px",
+                background: "var(--purpur-color-background-surface)",
+              }}
+            >
+              <Heading tag="h3" style={{ marginBottom: "8px" }}>
+                ⚡ Quick Actions
+              </Heading>
+              <p style={{ color: "var(--purpur-color-text-secondary)" }}>New feature!</p>
+              <Popover multistep step={2}>
+                <Popover.Trigger>
+                  <Button variant="primary" size="sm">
+                    Quick Actions
+                  </Button>
+                </Popover.Trigger>
+                <Popover.Content
+                  beakPosition={typedArgs.step2BeakPosition}
+                  align="end"
+                  avoidCollisions={typedArgs.avoidCollisions}
+                  closeIconAriaLabel={typedArgs.closeIconAriaLabel}
+                  title="New: Quick Actions Menu"
+                  body="Access frequently used actions with one click. Customize your shortcuts here."
+                  onAction={handleAction}
+                />
+              </Popover>
+            </div>
+          </div>
+
+          {/* Step 3 - Bottom - Export Feature */}
+          <div
+            style={{
+              position: "absolute",
+              bottom: "100px",
+              left: "50%",
+              transform: "translateX(-50%)",
+            }}
+          >
+            <div
+              style={{
+                border: "2px dashed var(--purpur-color-border-primary)",
+                padding: "20px",
+                borderRadius: "8px",
+                background: "var(--purpur-color-background-surface)",
+              }}
+            >
+              <Heading tag="h3" style={{ marginBottom: "8px" }}>
+                💾 Export Center
+              </Heading>
+              <p style={{ color: "var(--purpur-color-text-secondary)" }}>New feature!</p>
+              <Popover multistep step={3}>
+                <Popover.Trigger>
+                  <Button variant="primary" size="sm">
+                    Export Data
+                  </Button>
+                </Popover.Trigger>
+                <Popover.Content
+                  beakPosition={typedArgs.step3BeakPosition}
+                  avoidCollisions={typedArgs.avoidCollisions}
+                  closeIconAriaLabel={typedArgs.closeIconAriaLabel}
+                  title="New: Advanced Export Options"
+                  body="Export your data in multiple formats. Schedule automatic exports and more."
+                  onAction={handleAction}
+                />
+              </Popover>
+            </div>
+          </div>
+
+          {/* Step 4 - Middle - Main CTA */}
+          <div
+            style={{
+              position: "absolute",
+              top: "50%",
+              left: "50%",
+              transform: "translate(-50%, -50%)",
+            }}
+          >
+            <div
+              style={{
+                backgroundColor: "var(--purpur-color-background-tone-on-tone-primary)",
+                padding: "80px 120px",
+                borderRadius: "8px",
+                display: "flex",
+                flexDirection: "column",
+                justifyContent: "center",
+                alignItems: "center",
+                width: "500px",
+                height: "250px",
+                gap: "20px",
+              }}
+            >
+              <Heading tag="h2" negative style={{ textAlign: "center" }}>
+                Ready to explore?
+              </Heading>
+              <Popover multistep step={4}>
+                <Popover.Trigger>
+                  <Link href="#" variant="standalone" negative>
+                    Start Using New Features
+                  </Link>
+                </Popover.Trigger>
+                <Popover.Content
+                  negative
+                  beakPosition={typedArgs.step4BeakPosition}
+                  avoidCollisions={typedArgs.avoidCollisions}
+                  closeIconAriaLabel={typedArgs.closeIconAriaLabel}
+                  title="You're All Set!"
+                  body="Click here to start using the new features. We'll save your preferences and won't show this tour again."
+                  onAction={handleAction}
+                />
+              </Popover>
+              <Paragraph negative>
+                After completing the tour, focus remains here by default. Consumers can handle the
+                &apos;finish&apos; or &apos;dismiss&apos; events to control what happens next.
+              </Paragraph>
+            </div>
+          </div>
+        </Popover.Flow>
+      </div>
+    );
+  },
+};
+
+export const Variants: StoryObj = {
+  argTypes: {
+    negative: {
+      control: "boolean",
+      description: "Use negative (light) variant",
+    },
+    beakPosition: {
+      control: "select",
+      options: ["Up", "Right", "Down", "Left", "None"],
+      description:
+        "Position of the popover beak/arrow (Up, Right, Down, Left). Use None to hide the arrow.",
+    },
+    align: {
+      control: "select",
+      options: ["start", "center", "end"],
+      description: "Alignment of the popover",
+    },
+    closeIconAriaLabel: {
+      control: "text",
+      description: "Accessible label for close icon",
+    },
+    headerTitle: {
+      control: "text",
+      description: "Title text (required prop in component, mapped from this control)",
+    },
+    headerIcon: {
+      control: "boolean",
+      description: "Show header icon (optional icon prop in component)",
+    },
+    body: {
+      control: "text",
+      description: "Body text content",
+    },
+    showFooter: {
+      control: "boolean",
+      description: "Show footer with button",
+    },
+    button: {
+      control: "boolean",
+      description: "Use button as trigger",
+    },
+    buttonText: {
+      control: "text",
+      description: "Footer button text",
+    },
+    highlight: {
+      control: "boolean",
+      description: "Highlight the trigger",
+    },
+  },
+  render: () => {
+    return (
+      <div>
+        <div
+          style={{
+            display: "flex",
+            width: "800px",
+            height: "500px",
+            gap: "200px",
+          }}
+        >
+          <div>
+            <Popover>
+              <Popover.Trigger>
+                <Button variant="primary">Default</Button>
+              </Popover.Trigger>
+              <Popover.Content
+                beakPosition="down"
+                closeIconAriaLabel="Close"
+                title="Default variant"
+                body="This has the default dark background."
+              >
+                <Popover.Footer>
+                  <Popover.Button>Got it</Popover.Button>
+                </Popover.Footer>
+              </Popover.Content>
+            </Popover>
+          </div>
+
+          <div
+            style={{
+              backgroundColor: "var(--purpur-color-background-tone-on-tone-primary)",
+              padding: "20px",
+              borderRadius: "8px",
+              height: "500px",
+              width: "500px",
+            }}
+          >
+            <div
+              style={{
+                width: "fit-content",
+              }}
+            >
+              <Popover>
+                <Popover.Trigger negative>
+                  <Button variant="primary" negative>
+                    Negative
+                  </Button>
+                </Popover.Trigger>
+                <Popover.Content
+                  negative
+                  closeIconAriaLabel="Close"
+                  title="Negative variant"
+                  body="This has a light background with dark text."
+                  align="start"
+                  beakPosition="up"
+                >
+                  <Popover.Footer>
+                    <Popover.Button>Got it</Popover.Button>
+                  </Popover.Footer>
+                </Popover.Content>
+              </Popover>
+            </div>
+          </div>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const BeakPlacements: StoryObj = {
+  render: () => {
+    return (
+      <div
+        style={{
+          padding: "100px",
+          display: "flex",
+          flexDirection: "column",
+          gap: "60px",
+        }}
+      >
+        {/* Basic Positions */}
+        <div>
+          <Heading tag="h3" style={{ marginBottom: "20px", fontSize: "18px", fontWeight: "600" }}>
+            Basic Positions
+          </Heading>
+          <div
+            style={{
+              display: "flex",
+              gap: "32px",
+              flexWrap: "wrap",
+            }}
+          >
+            {(["up", "down", "left", "right"] as const).map((position) => (
+              <Popover key={position}>
+                <Popover.Trigger>
+                  <Button variant="primary">Beak {position}</Button>
+                </Popover.Trigger>
+                <Popover.Content
+                  beakPosition={position}
+                  closeIconAriaLabel="Close"
+                  title={`Beak ${position}`}
+                  body={`The popover beak points ${position.toLowerCase()}.`}
+                >
+                  <Popover.Footer>
+                    <Popover.Button>Got it</Popover.Button>
+                  </Popover.Footer>
+                </Popover.Content>
+              </Popover>
+            ))}
+            <Popover>
+              <Popover.Trigger>
+                <Button variant="primary">No Arrow</Button>
+              </Popover.Trigger>
+              <Popover.Content
+                beakPosition="none"
+                closeIconAriaLabel="Close"
+                title="No Arrow"
+                body="The popover has no arrow."
+              >
+                <Popover.Footer>
+                  <Popover.Button>Got it</Popover.Button>
+                </Popover.Footer>
+              </Popover.Content>
+            </Popover>
+          </div>
+        </div>
+
+        {/* Custom Alignment */}
+        <div>
+          <Heading tag="h3" style={{ marginBottom: "20px", fontSize: "18px", fontWeight: "600" }}>
+            Custom Alignment (Bottom Position)
+          </Heading>
+          <div
+            style={{
+              display: "flex",
+              gap: "32px",
+              flexWrap: "wrap",
+            }}
+          >
+            {(["start", "center", "end"] as const).map((align) => (
+              <Popover key={align}>
+                <Popover.Trigger>
+                  <Button variant="primary">Align {align}</Button>
+                </Popover.Trigger>
+                <Popover.Content
+                  beakPosition="down"
+                  align={align}
+                  closeIconAriaLabel="Close"
+                  title={`Aligned ${align}`}
+                  body={`The popover is aligned to the ${align} of the content.`}
+                >
+                  <Popover.Footer>
+                    <Popover.Button>Got it</Popover.Button>
+                  </Popover.Footer>
+                </Popover.Content>
+              </Popover>
+            ))}
+          </div>
+        </div>
+
+        {/* Custom Offset */}
+        <div>
+          <Heading tag="h3" style={{ marginBottom: "20px", fontSize: "18px", fontWeight: "600" }}>
+            Custom Offset
+          </Heading>
+          <div
+            style={{
+              display: "flex",
+              flexDirection: "column",
+              gap: "40px",
+            }}
+          >
+            {/* Start aligned with offsets */}
+            <div>
+              <Heading
+                tag="h4"
+                style={{ marginBottom: "12px", fontSize: "14px", fontWeight: "500" }}
+              >
+                Start Aligned (Bottom Position)
+              </Heading>
+              <div style={{ display: "flex", gap: "32px", flexWrap: "wrap" }}>
+                {([0, 35, -35] as const).map((offset) => (
+                  <Popover key={`start-${offset}`}>
+                    <Popover.Trigger>
+                      <Button variant="primary">Offset {offset}px</Button>
+                    </Popover.Trigger>
+                    <Popover.Content
+                      beakPosition="down"
+                      align="start"
+                      alignOffset={offset}
+                      closeIconAriaLabel="Close"
+                      title={`Start ${offset}px`}
+                      body={`Start aligned with ${offset}px offset from the start.`}
+                    >
+                      <Popover.Footer>
+                        <Popover.Button>Got it</Popover.Button>
+                      </Popover.Footer>
+                    </Popover.Content>
+                  </Popover>
+                ))}
+              </div>
+            </div>
+
+            <div>
+              <Heading
+                tag="h4"
+                style={{ marginBottom: "12px", fontSize: "14px", fontWeight: "500" }}
+              >
+                Start Aligned (Left Position)
+              </Heading>
+              <div style={{ display: "flex", gap: "32px", flexWrap: "wrap" }}>
+                {([0, 15, -25] as const).map((offset) => (
+                  <Popover key={`start-${offset}`}>
+                    <Popover.Trigger>
+                      <Button variant="primary">Offset {offset}px</Button>
+                    </Popover.Trigger>
+                    <Popover.Content
+                      beakPosition="left"
+                      align="start"
+                      alignOffset={offset}
+                      closeIconAriaLabel="Close"
+                      title={`Start ${offset}px`}
+                      body={`Start aligned with ${offset}px offset from the start.`}
+                    >
+                      <Popover.Footer>
+                        <Popover.Button>Got it</Popover.Button>
+                      </Popover.Footer>
+                    </Popover.Content>
+                  </Popover>
+                ))}
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    );
+  },
+};