[WRFE-91](refactor): Popover 리팩토링

eric-hjh · eric-hjh · commit 0304d88ce794 · 2025-05-13T23:21:31.000+09:00
diff --git a/packages/ui/src/ui/popover/Popover.mdx b/packages/ui/src/ui/popover/Popover.mdx
@@ -0,0 +1,105 @@
+{/* Popover.mdx */}
+
+import * as stories from './Popover.stories';
+import {Canvas, Meta, Primary, Controls, Description} from '@storybook/blocks';
+
+<Meta of={stories} />
+
+# Popover
+
+`Popover`는 합성 컴포넌트입니다. 버튼 클릭 시 추가적인 정보를 보여주는 데 사용됩니다.
+
+- [Overview](#overview)
+- [Props](#props)
+- [Description](#description)
+
+## Overview
+
+<Primary />
+
+## Props
+
+<Controls />
+
+## 컴포넌트 구조
+
+`Popover`는 다음과 같은 하위 컴포넌트들로 구성됩니다:
+
+- `Popover`: 최상위 컴포넌트
+- `PopoverTrigger`: Popover를 열고 닫는 트리거 컴포넌트
+- `PopoverContent`: Popover의 내용을 표시하는 컴포넌트
+- `PopoverAnchor`: Popover의 위치를 지정하는 기준점 컴포넌트
+
+## PopoverContent Props
+
+PopoverContent 컴포넌트는 다음과 같은 props를 받습니다:
+
+- `align`: Popover content의 정렬 방향 ('start' | 'center' | 'end', 기본값: 'center')
+- `sideOffset`: Trigger와 content 사이의 거리 (number, 기본값: 6)
+- `className`: 커스텀 스타일링을 위한 클래스 (string)
+
+## 스타일링
+
+Popover는 기본적으로 다음과 같은 스타일이 적용됩니다:
+
+- z-index: 50
+- 최소 너비: 트리거 요소의 너비
+- 둥근 모서리
+- 테두리
+- 그림자 효과
+- 애니메이션 효과 (열기/닫기)
+
+이러한 스타일은 `className` prop을 통해 커스터마이즈할 수 있습니다.
+
+## usePopover Hook
+
+`usePopover` 훅을 사용하면 Popover의 상태를 더 쉽게 관리할 수 있습니다.
+
+### 사용 예시
+
+```tsx
+import {PopoverProvider, usePopover} from './use-popover';
+
+const MyComponent = () => {
+  const {openPopover, closePopover} = usePopover();
+
+  return (
+    <button
+      onClick={() =>
+        openPopover(
+          <div>
+            <p>Popover Content</p>
+            <button onClick={closePopover}>Close</button>
+          </div>,
+        )
+      }
+    >
+      Open Popover
+    </button>
+  );
+};
+
+// 최상위 컴포넌트에서 Provider로 감싸기
+const App = () => (
+  <PopoverProvider>
+    <MyComponent />
+  </PopoverProvider>
+);
+```
+
+### Hook API
+
+usePopover 훅은 다음과 같은 값들을 반환합니다:
+
+- `content`: 현재 Popover에 표시되는 컨텐츠 (ReactNode)
+- `openPopover`: Popover를 열고 컨텐츠를 설정하는 함수 ((content: ReactNode) => void)
+- `closePopover`: Popover를 닫는 함수 (() => void)
+
+## 접근성
+
+Popover는 Radix UI의 Popover 컴포넌트를 기반으로 하며, 다음과 같은 접근성 기능을 제공합니다:
+
+- 키보드 네비게이션 지원
+- ARIA 속성 자동 관리
+- 포커스 관리
+- ESC 키를 통한 닫기
diff --git a/packages/ui/src/ui/popover/Popover.stories.tsx b/packages/ui/src/ui/popover/Popover.stories.tsx
@@ -0,0 +1,101 @@
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverAnchor,
+} from './Popover';
+import {PopoverProvider, usePopover} from './use-popover';
+import type {Meta, StoryObj} from '@storybook/react';
+
+const meta: Meta = {
+  title: 'Components/Popover',
+  argTypes: {
+    align: {
+      control: 'select',
+      options: ['start', 'center', 'end'],
+      description: 'Popover content alignment',
+    },
+    sideOffset: {
+      control: 'number',
+      description: 'Distance between trigger and content',
+    },
+    className: {
+      control: 'text',
+      description: 'Custom class for styling',
+    },
+  },
+};
+
+export default meta;
+
+export const Default: StoryObj = {
+  render: args => (
+    <Popover>
+      <PopoverTrigger className='rounded border p-2'>
+        Open Popover
+      </PopoverTrigger>
+      <PopoverContent {...args}>Popover Content</PopoverContent>
+    </Popover>
+  ),
+};
+
+export const WithAnchor: StoryObj = {
+  render: () => (
+    <Popover>
+      <PopoverAnchor className='absolute right-0 top-0' />
+      <PopoverTrigger className='rounded border p-2'>
+        Open Popover
+      </PopoverTrigger>
+      <PopoverContent className='border bg-white p-4 shadow-md'>
+        Popover Content with Anchor
+      </PopoverContent>
+    </Popover>
+  ),
+};
+
+const PopoverWithHook = () => {
+  const {openPopover, closePopover} = usePopover();
+
+  return (
+    <div className='flex gap-4'>
+      <button
+        className='rounded border p-2'
+        onClick={() =>
+          openPopover(
+            <div className='flex flex-col gap-2'>
+              <p>This is a popover content using usePopover hook</p>
+              <button className='rounded border p-1' onClick={closePopover}>
+                Close
+              </button>
+            </div>,
+          )
+        }
+      >
+        Open Popover with Hook
+      </button>
+      <button
+        className='rounded border p-2'
+        onClick={() =>
+          openPopover(
+            <div className='flex flex-col gap-2'>
+              <p>This is another popover content</p>
+              <button className='rounded border p-1' onClick={closePopover}>
+                Close
+              </button>
+            </div>,
+          )
+        }
+      >
+        Open Another Popover
+      </button>
+    </div>
+  );
+};
+
+export const WithHook: StoryObj = {
+  render: () => (
+    <PopoverProvider>
+      <PopoverWithHook />
+    </PopoverProvider>
+  ),
+};
diff --git a/packages/ui/src/ui/popover/Popover.tsx b/packages/ui/src/ui/popover/Popover.tsx
@@ -0,0 +1,34 @@
+'use client';
+
+import clsx from 'clsx';
+import * as React from 'react';
+import * as PopoverPrimitive from '@radix-ui/react-popover';
+
+const Popover = PopoverPrimitive.Root;
+
+const PopoverTrigger = PopoverPrimitive.Trigger;
+
+const PopoverAnchor = PopoverPrimitive.Anchor;
+
+const PopoverContent = React.forwardRef<
+  React.ElementRef<typeof PopoverPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>
+>(({className, align = 'center', sideOffset = 6, ...props}, ref) => (
+  <PopoverPrimitive.Portal>
+    <PopoverPrimitive.Content
+      ref={ref}
+      align={align}
+      sideOffset={sideOffset}
+      className={clsx(
+        'z-50 w-full min-w-[var(--radix-popper-anchor-width)] rounded-md border bg-popover p-3 text-popover-foreground shadow-md outline-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
+        className,
+      )}
+      {...props}
+    >
+      {props.children}
+    </PopoverPrimitive.Content>
+  </PopoverPrimitive.Portal>
+));
+PopoverContent.displayName = PopoverPrimitive.Content.displayName;
+
+export {Popover, PopoverTrigger, PopoverContent, PopoverAnchor};
diff --git a/packages/ui/src/ui/popover/use-popover.tsx b/packages/ui/src/ui/popover/use-popover.tsx
@@ -0,0 +1,47 @@
+import {Popover, PopoverContent, PopoverTrigger} from './Popover';
+import React, {useState} from 'react';
+
+const PopoverContext = React.createContext<{
+  content: React.ReactNode;
+  openPopover: (content: React.ReactNode) => void;
+  closePopover: () => void;
+}>({
+  content: null,
+  openPopover: () => {},
+  closePopover: () => {},
+});
+
+interface PopoverProviderProps {
+  children: React.ReactNode;
+}
+
+export const PopoverProvider = ({children}: PopoverProviderProps) => {
+  const [content, setContent] = useState<React.ReactNode>(null);
+  const [isOpen, setIsOpen] = useState(false);
+
+  const openPopover = (newContent: React.ReactNode) => {
+    setContent(newContent);
+    setIsOpen(true);
+  };
+
+  const closePopover = () => {
+    setIsOpen(false);
+  };
+
+  return (
+    <PopoverContext.Provider value={{content, openPopover, closePopover}}>
+      <Popover open={isOpen} onOpenChange={setIsOpen}>
+        <PopoverTrigger>{children}</PopoverTrigger>
+        <PopoverContent>{content}</PopoverContent>
+      </Popover>
+    </PopoverContext.Provider>
+  );
+};
+
+export const usePopover = () => {
+  const context = React.useContext(PopoverContext);
+  if (!context) {
+    throw new Error('usePopover must be used within a PopoverProvider');
+  }
+  return context;
+};
