@fpkit/acss 6.2.0 → 6.3.0

package/src/components/popover/popover.stories.tsx

@@ -1,30 +1,330 @@
 import { StoryObj, Meta } from "@storybook/react-vite";
 import { within, expect, userEvent } from "storybook/test";
+import { useState } from "react";
 
-import Popover from "./popover";
+import { Popover } from "./popover";
+import type {} from "../../types/popover";
+import "./popover.scss";
 
 const meta: Meta<typeof Popover> = {
-  title: "FP.React Components/Basic Popover",
+  title: "FP.React Components/Popover",
   component: Popover,
-  tags: ["experimental"],
-  args: {
-    children: "Hi, I am a popover.",
-    popoverTrigger: "Hover here",
-    styles: Popover.styles,
+  tags: ["stable"],
+  parameters: {
+    layout: "centered",
+    docs: {
+      description: {
+        component:
+          "Native HTML Popover API component with automatic top-layer rendering, light dismiss, and accessibility features. Requires Chrome 125+, Edge 125+, or Safari 17.4+.",
+      },
+    },
+  },
+  argTypes: {
+    mode: {
+      control: "select",
+      options: ["auto", "manual"],
+      description: "Popover dismiss behavior",
+    },
+    placement: {
+      control: "select",
+      options: ["top", "bottom", "left", "right"],
+      description: "Preferred placement position",
+    },
+    showArrow: {
+      control: "boolean",
+      description: "Show positioning arrow",
+    },
+    showCloseButton: {
+      control: "boolean",
+      description: "Show close button",
+    },
   },
 } as Meta;
 
 export default meta;
 type Story = StoryObj<typeof Popover>;
 
-export const PopoverComponent: Story = {
-  args: {},
-  play: async ({ canvasElement }) => {
+/**
+ * Default auto-dismiss popover with bottom placement
+ */
+export const Default: Story = {
+  args: {
+    id: "default-popover",
+    triggerLabel: "Open Popover",
+    children: (
+      <>
+        <h3 style={{ margin: "0 0 0.5rem 0", fontSize: "1.125rem" }}>
+          Popover Title
+        </h3>
+        <p style={{ margin: 0, fontSize: "0.875rem" }}>
+          This popover dismisses automatically when you click outside or press
+          Escape.
+        </p>
+      </>
+    ),
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step("Render trigger button", async () => {
+      const trigger = canvas.getByRole("button", { name: "Open Popover" });
+      expect(trigger).toBeInTheDocument();
+    });
+
+    await step("Click trigger opens popover", async () => {
+      const trigger = canvas.getByRole("button", { name: "Open Popover" });
+      await userEvent.click(trigger);
+      expect(canvas.getByText("Popover Title")).toBeInTheDocument();
+    });
+
+    await step("Escape key closes popover (auto mode)", async () => {
+      await userEvent.keyboard("{Escape}");
+      // Wait for animation
+      await new Promise((resolve) => setTimeout(resolve, 300));
+      expect(canvas.queryByText("Popover Title")).not.toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Manual mode requires explicit close action
+ */
+export const ManualMode: Story = {
+  args: {
+    id: "manual-popover",
+    triggerLabel: "Open Manual Popover",
+    mode: "manual",
+    children: (
+      <>
+        <h3 style={{ margin: "0 0 0.5rem 0", fontSize: "1.125rem" }}>
+          Manual Popover
+        </h3>
+        <p style={{ margin: 0, fontSize: "0.875rem" }}>
+          This popover requires clicking the close button or trigger to dismiss.
+          It includes a backdrop overlay.
+        </p>
+      </>
+    ),
+  },
+  play: async ({ canvasElement, step }) => {
     const canvas = within(canvasElement);
-    expect(await canvas.queryByText("Hover here")).toBeInTheDocument();
-    userEvent.hover(canvas.getByText("Hover here"));
-    expect(await canvas.findByText("Hi, I am a popover.")).toBeInTheDocument();
-    await userEvent.unhover(canvas.getByText("Hover here"));
-    expect(canvas.queryByText("Hi, I am a popover.")).not.toBeInTheDocument();
+
+    await step("Click trigger opens popover", async () => {
+      const trigger = canvas.getByRole("button", {
+        name: "Open Manual Popover",
+      });
+      await userEvent.click(trigger);
+      expect(canvas.getByText("Manual Popover")).toBeInTheDocument();
+    });
+
+    await step("Close button dismisses popover", async () => {
+      const closeButton = canvas.getByRole("button", { name: "Close" });
+      await userEvent.click(closeButton);
+      // Wait for animation
+      await new Promise((resolve) => setTimeout(resolve, 300));
+      expect(canvas.queryByText("Manual Popover")).not.toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Popover with top placement
+ */
+export const TopPlacement: Story = {
+  args: {
+    id: "top-popover",
+    triggerLabel: "Open Above",
+    placement: "top",
+    children: (
+      <p style={{ margin: 0 }}>This popover appears above the trigger</p>
+    ),
+  },
+};
+
+/**
+ * Popover with left placement
+ */
+export const LeftPlacement: Story = {
+  args: {
+    id: "left-popover",
+    triggerLabel: "Open Left",
+    placement: "left",
+    children: <p style={{ margin: 0 }}>This popover appears to the left</p>,
+  },
+};
+
+/**
+ * Popover with right placement
+ */
+export const RightPlacement: Story = {
+  args: {
+    id: "right-popover",
+    triggerLabel: "Open Right",
+    placement: "right",
+    children: <p style={{ margin: 0 }}>This popover appears to the right</p>,
+  },
+};
+
+/**
+ * Custom trigger element
+ */
+export const CustomTrigger: Story = {
+  args: {
+    id: "custom-trigger-popover",
+    trigger: (
+      <button style={{ padding: "0.5rem 1rem", borderRadius: "2rem" }}>
+        🎨 Custom
+      </button>
+    ),
+    children: (
+      <>
+        <h4 style={{ margin: "0 0 0.5rem 0" }}>Custom Trigger</h4>
+        <p style={{ margin: 0, fontSize: "0.875rem" }}>
+          You can use any React element as trigger
+        </p>
+      </>
+    ),
+  },
+};
+
+/**
+ * Popover without arrow
+ */
+export const NoArrow: Story = {
+  args: {
+    id: "no-arrow-popover",
+    triggerLabel: "No Arrow",
+    showArrow: false,
+    children: <p style={{ margin: 0 }}>This popover has no arrow indicator</p>,
+  },
+};
+
+/**
+ * Popover with custom styling via CSS variables
+ */
+export const CustomStyling: Story = {
+  args: {
+    id: "custom-styled-popover",
+    triggerLabel: "Custom Style",
+    styles: {
+      "--popover-bg": "#1a1a2e",
+      "--popover-border": "0.125rem solid #16213e",
+      "--popover-border-radius": "0.75rem",
+      "--popover-padding": "1.5rem",
+      "--popover-shadow": "0 0.5rem 1rem rgba(0, 0, 0, 0.3)",
+      color: "#eee",
+    } as React.CSSProperties,
+    children: (
+      <>
+        <h3 style={{ margin: "0 0 0.5rem 0", color: "#0f3" }}>Dark Theme</h3>
+        <p style={{ margin: 0, fontSize: "0.875rem" }}>
+          Customize appearance using CSS custom properties
+        </p>
+      </>
+    ),
+  },
+};
+
+/**
+ * Controlled popover with external state
+ */
+const ControlledExample = () => {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", alignItems: "center", gap: "1rem" }}>
+      <Popover
+        id="controlled-popover"
+        triggerLabel="Toggle Popover"
+        isOpen={isOpen}
+        onToggle={setIsOpen}
+      >
+        <div>
+          <h4 style={{ margin: "0 0 0.5rem 0" }}>Controlled Popover</h4>
+          <p style={{ margin: "0 0 0.5rem 0", fontSize: "0.875rem" }}>
+            State is managed externally
+          </p>
+          <button
+            onClick={() => setIsOpen(false)}
+            style={{ padding: "0.25rem 0.5rem", fontSize: "0.75rem" }}
+          >
+            Close via State
+          </button>
+        </div>
+      </Popover>
+      <div style={{ textAlign: "center" }}>
+        <p style={{ margin: "0 0 0.5rem 0" }}>Current state: {isOpen ? "Open" : "Closed"}</p>
+        <button onClick={() => setIsOpen(!isOpen)}>External Toggle</button>
+      </div>
+    </div>
+  );
+};
+
+export const Controlled: Story = {
+  render: () => <ControlledExample />,
+};
+
+/**
+ * Popover with form content
+ */
+export const WithForm: Story = {
+  args: {
+    id: "form-popover",
+    triggerLabel: "Show Form",
+    mode: "manual",
+    children: (
+      <form
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: "0.75rem",
+          minWidth: "15rem",
+        }}
+        onSubmit={(e) => {
+          e.preventDefault();
+          alert("Form submitted!");
+        }}
+      >
+        <h4 style={{ margin: 0 }}>Contact Form</h4>
+        <input
+          type="text"
+          placeholder="Name"
+          style={{
+            padding: "0.5rem",
+            border: "0.0625rem solid #ccc",
+            borderRadius: "0.25rem",
+          }}
+        />
+        <input
+          type="email"
+          placeholder="Email"
+          style={{
+            padding: "0.5rem",
+            border: "0.0625rem solid #ccc",
+            borderRadius: "0.25rem",
+          }}
+        />
+        <textarea
+          placeholder="Message"
+          rows={3}
+          style={{
+            padding: "0.5rem",
+            border: "0.0625rem solid #ccc",
+            borderRadius: "0.25rem",
+          }}
+        />
+        <button
+          type="submit"
+          style={{
+            padding: "0.5rem",
+            background: "#0066cc",
+            color: "#fff",
+            border: "none",
+          }}
+        >
+          Submit
+        </button>
+      </form>
+    ),
   },
 };

package/src/components/popover/popover.test.tsx

@@ -1,39 +1,251 @@
-import React from 'react'
-import { render, screen, fireEvent } from '@testing-library/react'
-import Popover from './popover'
-import userEvent from '@testing-library/user-event'
+import React from 'react';
+import { render, screen, waitFor } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Popover } from './popover';
+import type {} from '../../types/popover';
+
+// Mock showPopover and hidePopover methods
+beforeEach(() => {
+  HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+    this.setAttribute('data-popover-open', 'true');
+  }) as unknown as () => void;
+
+  HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+    this.removeAttribute('data-popover-open');
+  }) as unknown as () => void;
+
+  HTMLElement.prototype.togglePopover = vi.fn(function (this: HTMLElement) {
+    if (this.hasAttribute('data-popover-open')) {
+      this.removeAttribute('data-popover-open');
+    } else {
+      this.setAttribute('data-popover-open', 'true');
+    }
+  }) as unknown as (force?: boolean) => void;
+});
 
 describe('Popover', () => {
-  it('renders the popover content when the trigger element is hovered', async () => {
-    render(
-      <Popover popoverTrigger={<button>Hover here</button>}>
-        Popover content
-      </Popover>,
-    )
-
-    const triggerElement = screen.getByRole('button', {
-      name: /hover here/i,
-    })
-    userEvent.hover(triggerElement)
-    expect(await screen.findByText('Popover content')).toBeInTheDocument()
-  })
-
-  it('hides the popover content when the trigger element is no longer hovered', () => {
-    render(
-      <Popover popoverTrigger={<button>Hover here</button>}>
-        Popover content
-      </Popover>,
-    )
-
-    const triggerElement = screen.getByRole('button', {
-      name: /hover here/i,
-    })
-    fireEvent.pointerEnter(triggerElement)
-
-    const popoverContent = screen.getByText('Popover content')
-    expect(popoverContent).toBeInTheDocument()
-
-    fireEvent.pointerLeave(triggerElement)
-    expect(popoverContent).not.toBeInTheDocument()
-  })
-})
+  it('renders trigger button with default label', () => {
+    render(
+      <Popover id="test-popover" triggerLabel="Open Menu">
+        <p>Content</p>
+      </Popover>
+    );
+
+    const trigger = screen.getByRole('button', { name: 'Open Menu' });
+    expect(trigger).toBeInTheDocument();
+    expect(trigger).toHaveAttribute('popovertarget', 'test-popover');
+  });
+
+  it('renders popover content with correct attributes', () => {
+    render(
+      <Popover id="test-popover" mode="auto" placement="bottom">
+        <p>Popover content</p>
+      </Popover>
+    );
+
+    const popover = screen.getByText('Popover content').closest('[popover]');
+    expect(popover).toBeInTheDocument();
+    expect(popover).toHaveAttribute('popover', 'auto');
+    expect(popover).toHaveAttribute('data-placement', 'bottom');
+  });
+
+  it('uses custom trigger element', () => {
+    render(
+      <Popover id="test-popover" trigger={<button>Custom Trigger</button>}>
+        <p>Content</p>
+      </Popover>
+    );
+
+    const trigger = screen.getByRole('button', { name: 'Custom Trigger' });
+    expect(trigger).toBeInTheDocument();
+    expect(trigger).toHaveAttribute('popovertarget', 'test-popover');
+  });
+
+  it('shows close button in manual mode by default', () => {
+    render(
+      <Popover id="test-popover" mode="manual">
+        <p>Content</p>
+      </Popover>
+    );
+
+    const closeButton = screen.getByRole('button', { name: 'Close' });
+    expect(closeButton).toBeInTheDocument();
+    expect(closeButton).toHaveAttribute('popovertargetaction', 'hide');
+  });
+
+  it('hides close button in auto mode by default', () => {
+    render(
+      <Popover id="test-popover" mode="auto">
+        <p>Content</p>
+      </Popover>
+    );
+
+    const closeButton = screen.queryByRole('button', { name: 'Close' });
+    expect(closeButton).not.toBeInTheDocument();
+  });
+
+  it('respects showCloseButton prop override', () => {
+    render(
+      <Popover id="test-popover" mode="auto" showCloseButton={true}>
+        <p>Content</p>
+      </Popover>
+    );
+
+    const closeButton = screen.getByRole('button', { name: 'Close' });
+    expect(closeButton).toBeInTheDocument();
+  });
+
+  it('shows arrow by default', () => {
+    const { container } = render(
+      <Popover id="test-popover">
+        <p>Content</p>
+      </Popover>
+    );
+
+    const arrow = container.querySelector('.fpkit-popover-arrow');
+    expect(arrow).toBeInTheDocument();
+  });
+
+  it('hides arrow when showArrow is false', () => {
+    const { container } = render(
+      <Popover id="test-popover" showArrow={false}>
+        <p>Content</p>
+      </Popover>
+    );
+
+    const arrow = container.querySelector('.fpkit-popover-arrow');
+    expect(arrow).not.toBeInTheDocument();
+  });
+
+  it('applies custom className', () => {
+    const { container } = render(
+      <Popover id="test-popover" className="custom-class">
+        <p>Content</p>
+      </Popover>
+    );
+
+    const popover = container.querySelector('.fpkit-popover.custom-class');
+    expect(popover).toBeInTheDocument();
+  });
+
+  it('applies inline styles', () => {
+    const customStyles = { '--popover-bg': '#000000' } as React.CSSProperties;
+    const { container } = render(
+      <Popover id="test-popover" styles={customStyles}>
+        <p>Content</p>
+      </Popover>
+    );
+
+    const popover = container.querySelector('.fpkit-popover') as HTMLElement;
+    expect(popover.style.getPropertyValue('--popover-bg')).toBe('#000000');
+  });
+
+  it('calls onToggle callback when popover state changes', async () => {
+    const handleToggle = vi.fn();
+    const { container } = render(
+      <Popover id="test-popover" onToggle={handleToggle}>
+        <p>Content</p>
+      </Popover>
+    );
+
+    const popover = container.querySelector('[popover]') as HTMLElement;
+
+    // Simulate toggle event - open
+    const toggleEventOpen = Object.assign(new Event('toggle'), {
+      newState: 'open' as const,
+      oldState: 'closed' as const,
+    }) as ToggleEvent;
+    popover.dispatchEvent(toggleEventOpen);
+
+    await waitFor(() => {
+      expect(handleToggle).toHaveBeenCalledWith(true);
+    });
+
+    // Simulate close
+    const toggleEventClose = Object.assign(new Event('toggle'), {
+      newState: 'closed' as const,
+      oldState: 'open' as const,
+    }) as ToggleEvent;
+    popover.dispatchEvent(toggleEventClose);
+
+    await waitFor(() => {
+      expect(handleToggle).toHaveBeenCalledWith(false);
+    });
+  });
+
+  it('handles controlled state with isOpen prop', async () => {
+    const { rerender, container } = render(
+      <Popover id="test-popover" isOpen={false}>
+        <p>Content</p>
+      </Popover>
+    );
+
+    const popover = container.querySelector('[popover]') as HTMLElement;
+
+    // Initially closed
+    expect(popover.hasAttribute('data-popover-open')).toBe(false);
+
+    // Open popover
+    rerender(
+      <Popover id="test-popover" isOpen={true}>
+        <p>Content</p>
+      </Popover>
+    );
+
+    await waitFor(() => {
+      expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
+    });
+  });
+
+  it('generates unique ID when not provided', () => {
+    const { container } = render(
+      <Popover>
+        <p>Content</p>
+      </Popover>
+    );
+
+    const popover = container.querySelector('[popover]');
+    const trigger = screen.getByRole('button');
+
+    expect(popover).toHaveAttribute('id');
+    expect(trigger).toHaveAttribute('popovertarget');
+
+    const popoverId = popover?.getAttribute('id');
+    const triggerId = trigger.getAttribute('popovertarget');
+
+    expect(popoverId).toBe(triggerId);
+  });
+
+  it('uses provided ID', () => {
+    render(
+      <Popover id="custom-id">
+        <p>Content</p>
+      </Popover>
+    );
+
+    const trigger = screen.getByRole('button');
+    expect(trigger).toHaveAttribute('popovertarget', 'custom-id');
+  });
+
+  it('custom close button label', () => {
+    render(
+      <Popover id="test-popover" mode="manual" closeButtonLabel="Dismiss">
+        <p>Content</p>
+      </Popover>
+    );
+
+    const closeButton = screen.getByRole('button', { name: 'Dismiss' });
+    expect(closeButton).toBeInTheDocument();
+  });
+
+  it('renders arrow with correct placement attribute', () => {
+    const { container } = render(
+      <Popover id="test-popover" placement="top">
+        <p>Content</p>
+      </Popover>
+    );
+
+    const arrow = container.querySelector('.fpkit-popover-arrow');
+    expect(arrow).toHaveAttribute('data-placement', 'top');
+  });
+});