feat: 디자인 시스템 - Tooltip(툴팁) 컴포넌트 구현

packages/jds/src/components/Icon/Icon.tsx

@@ -1,17 +1,23 @@
+import { type ElementRef, forwardRef } from 'react';
+
 import { StyledIconWrapper } from './Icon.styles';
 import type { IconProps } from './Icon.types';
 import { iconMap, sizeMap } from './IconMap';
 
-export const Icon = ({ name, size = 'md', color = 'currentColor', ...props }: IconProps) => {
-  const IconComponent = iconMap[name];
+export const Icon = forwardRef<ElementRef<typeof StyledIconWrapper>, IconProps>(
+  ({ name, size = 'md', color = 'currentColor', ...props }, ref) => {
+    const IconComponent = iconMap[name];
+
+    if (!IconComponent) return null;
 
-  if (!IconComponent) return null;
+    const pixelSize = sizeMap[size];
 
-  const pixelSize = sizeMap[size];
+    return (
+      <StyledIconWrapper ref={ref}>
+        <IconComponent width={pixelSize} height={pixelSize} color={color} {...props} />
+      </StyledIconWrapper>
+    );
+  },
+);
 
-  return (
-    <StyledIconWrapper>
-      <IconComponent width={pixelSize} height={pixelSize} color={color} {...props} />
-    </StyledIconWrapper>
-  );
-};
+Icon.displayName = 'Icon';

packages/jds/src/components/Label/Label.style.ts

@@ -2,14 +2,8 @@ import isPropValid from '@emotion/is-prop-valid';
 import type { Theme } from '@emotion/react';
 import styled from '@emotion/styled';
 
-const TEXT_ALIGN_MAPPING = {
-  center: 'center',
-  left: 'flex-start',
-  right: 'flex-end',
-} as const;
-
 export type LabelSize = 'lg' | 'md' | 'sm' | 'xs';
-export type LabelTextAlign = keyof typeof TEXT_ALIGN_MAPPING;
+export type LabelTextAlign = 'left' | 'center' | 'right';
 export type LabelWeight = 'bold' | 'normal' | 'subtle';
 
 interface LabelStyledProps {
@@ -32,12 +26,9 @@ export const LabelStyled = styled('label', {
   shouldForwardProp: prop => isPropValid(prop) && !prop.startsWith('$'),
 })<LabelStyledProps>(({ theme, $size, $textAlign, $weight, $color }) => {
   const tokenKey = getLabelTokenKey($size, $weight);
-  const justifyContent = TEXT_ALIGN_MAPPING[$textAlign];
 
   return {
-    display: 'flex',
-    justifyContent,
-    alignItems: 'center',
+    textAlign: $textAlign,
     color: $color ?? theme.color.semantic.object.bold,
     cursor: 'inherit',
     ...theme.textStyle[tokenKey],

packages/jds/src/components/Tooltip/Tooltip.stories.tsx

@@ -0,0 +1,231 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { FlexColumn, FlexRow, Label } from '@storybook-utils/layout';
+import { Icon, IconButton, Input, Tooltip, BlockButton } from 'components';
+import { Label as LabelComponent } from 'components';
+
+const meta = {
+  title: 'Components/Tooltip',
+  component: Tooltip.Content,
+  decorators: [
+    Story => (
+      <Tooltip.Provider delayDuration={0} skipDelayDuration={0}>
+        <Story />
+      </Tooltip.Provider>
+    ),
+  ],
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    side: {
+      control: 'select',
+      options: ['top', 'right', 'bottom', 'left'],
+      description: '툴팁 표시 위치',
+      table: {
+        defaultValue: { summary: 'top' },
+      },
+    },
+    sideOffset: {
+      control: 'number',
+      description: '트리거 요소와의 간격 (px)',
+      table: {
+        defaultValue: { summary: '8' },
+      },
+    },
+    avoidCollisions: {
+      control: 'boolean',
+      description: '뷰포트 충돌 방지 자동 위치 조정',
+      table: {
+        defaultValue: { summary: 'true' },
+      },
+    },
+  },
+} satisfies Meta<typeof Tooltip.Content>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: args => (
+    <Tooltip.Root>
+      <Tooltip.Trigger>
+        <IconButton.Basic icon='information-line' />
+      </Tooltip.Trigger>
+      <Tooltip.Content {...args}>툴팁 테스트 레이블</Tooltip.Content>
+    </Tooltip.Root>
+  ),
+  args: {
+    side: 'top',
+    sideOffset: 8,
+    avoidCollisions: true,
+  },
+};
+
+export const AllSides: Story = {
+  args: { children: undefined },
+  render: () => (
+    <FlexColumn gap='60px'>
+      <FlexRow gap='24px'>
+        <FlexColumn gap='12px'>
+          <Label>Top (기본값)</Label>
+          <Tooltip.Root>
+            <Tooltip.Trigger>
+              <IconButton.Basic icon='information-line' />
+            </Tooltip.Trigger>
+            <Tooltip.Content side='top'>툴팁 상단</Tooltip.Content>
+          </Tooltip.Root>
+        </FlexColumn>
+
+        <FlexColumn gap='12px'>
+          <Label>Right</Label>
+          <Tooltip.Root>
+            <Tooltip.Trigger>
+              <IconButton.Basic icon='information-line' />
+            </Tooltip.Trigger>
+            <Tooltip.Content side='right'>툴팁 우측</Tooltip.Content>
+          </Tooltip.Root>
+        </FlexColumn>
+
+        <FlexColumn gap='12px'>
+          <Label>Bottom</Label>
+          <Tooltip.Root>
+            <Tooltip.Trigger>
+              <IconButton.Basic icon='information-line' />
+            </Tooltip.Trigger>
+            <Tooltip.Content side='bottom'>툴팁 아래</Tooltip.Content>
+          </Tooltip.Root>
+        </FlexColumn>
+
+        <FlexColumn gap='12px'>
+          <Label>Left</Label>
+          <Tooltip.Root>
+            <Tooltip.Trigger>
+              <IconButton.Basic icon='information-line' />
+            </Tooltip.Trigger>
+            <Tooltip.Content side='left'>툴팁 좌측</Tooltip.Content>
+          </Tooltip.Root>
+        </FlexColumn>
+      </FlexRow>
+    </FlexColumn>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '툴팁은 네 가지 방향(top, right, bottom, left)으로 표시할 수 있습니다. avoidCollisions가 활성화되어 공간이 부족하면 자동으로 다른 방향으로 전환됩니다.',
+      },
+    },
+  },
+};
+
+export const LongContent: Story = {
+  args: { children: undefined },
+  render: () => (
+    <Tooltip.Root>
+      <Tooltip.Trigger>
+        <BlockButton.Basic hierarchy='accent'>표시되는 요소가 길 경우</BlockButton.Basic>
+      </Tooltip.Trigger>
+      <Tooltip.Content>
+        아주 아주 아주 아주 긴 요소입니다. 모바일 환경에서도 정상적인 툴팁 내용이 표시되어야하기
+        때문에 이러한 처리를 하였습니다. 최대 길이는 320px이며 이 후 자동으로 줄바꿈 됩니다.
+      </Tooltip.Content>
+    </Tooltip.Root>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: '긴 텍스트는 자동으로 줄바꿈되며, 최대 너비는 320px입니다.',
+      },
+    },
+  },
+};
+
+export const WithCustomOffset: Story = {
+  args: { children: undefined },
+  render: () => (
+    <FlexRow gap='24px'>
+      <FlexColumn gap='12px'>
+        <Label>오프셋 기본값(8px)</Label>
+        <Tooltip.Root>
+          <Tooltip.Trigger>
+            <BlockButton.Basic hierarchy='accent'>기본 오프셋</BlockButton.Basic>
+          </Tooltip.Trigger>
+          <Tooltip.Content sideOffset={8}>트리거 요소로 부터 8px</Tooltip.Content>
+        </Tooltip.Root>
+      </FlexColumn>
+
+      <FlexColumn gap='12px'>
+        <Label>오프셋 커스텀(24px)</Label>
+        <Tooltip.Root>
+          <Tooltip.Trigger>
+            <BlockButton.Basic hierarchy='accent'>커스텀(확장) 오프셋</BlockButton.Basic>
+          </Tooltip.Trigger>
+          <Tooltip.Content sideOffset={24}>트리거 요소로 부터 24px</Tooltip.Content>
+        </Tooltip.Root>
+      </FlexColumn>
+    </FlexRow>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'sideOffset prop으로 트리거 요소와 툴팁 사이의 간격을 조절할 수 있습니다.',
+      },
+    },
+  },
+};
+
+export const CustomTrigger: Story = {
+  args: { children: undefined },
+  render: () => (
+    <FlexColumn gap='24px'>
+      <div>
+        <Tooltip.Root>
+          <Tooltip.Trigger>
+            <LabelComponent as='span'>텍스트 레이블입니다.</LabelComponent>
+          </Tooltip.Trigger>
+          <Tooltip.Content>레이블</Tooltip.Content>
+        </Tooltip.Root>
+      </div>
+
+      <FlexColumn gap='12px'>
+        <Label>Icon 컴포넌트</Label>
+        <Tooltip.Root>
+          <Tooltip.Trigger>
+            <Icon name='information-line' size='lg' />
+          </Tooltip.Trigger>
+          <Tooltip.Content>아이콘 툴팁</Tooltip.Content>
+        </Tooltip.Root>
+      </FlexColumn>
+
+      <FlexColumn gap='12px'>
+        <Label>Icon 버튼</Label>
+        <Tooltip.Root>
+          <Tooltip.Trigger>
+            <IconButton.Basic icon='alert-line' />
+          </Tooltip.Trigger>
+          <Tooltip.Content>아이콘 버튼 툴팁</Tooltip.Content>
+        </Tooltip.Root>
+      </FlexColumn>
+
+      <FlexColumn gap='12px'>
+        <Label>Input 예시</Label>
+        <Tooltip.Root>
+          <Tooltip.Trigger>
+            <Input.TextField value='레이블 명' onChange={e => e.preventDefault()} />
+          </Tooltip.Trigger>
+          <Tooltip.Content side='top' sideOffset={12}>
+            안녕하세요? 툴팁입니다.
+          </Tooltip.Content>
+        </Tooltip.Root>
+      </FlexColumn>
+    </FlexColumn>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '툴팁은 다양한 Interactive한 요소에 적용할 수 있습니다. 다만, forwardRef 로 래핑된 요소나 Content 자체에 Html Element를 가진 요소이어야 합니다. 버튼, 텍스트, 아이콘, 입력 필드 등 어떤 요소든 트리거로 사용할 수 있습니다.',
+      },
+    },
+  },
+};

packages/jds/src/components/Tooltip/Tooltip.tsx

@@ -0,0 +1,57 @@
+import { Tooltip as TooltipPrimitive } from 'radix-ui';
+
+import { StyledTooltipContent } from './tooltip.styles';
+import type { TooltipContentProps, TooltipProps, TooltipTriggerProps } from './tooltip.types';
+
+const TooltipRoot = ({ children, delayDuration = 0, ...radixProps }: TooltipProps) => {
+  return (
+    <TooltipPrimitive.Root delayDuration={delayDuration} {...radixProps}>
+      {children}
+    </TooltipPrimitive.Root>
+  );
+};
+
+TooltipRoot.displayName = 'Tooltip.Root';
+
+//Todo: avoidCollisions로 제어되고 있는 위치 감지를 디자인 에셋에서 요구하는 감지 플로우로 변경 시 내부 Context 활용 필요 가능성
+const TooltipTrigger = ({ children, asChild = true, ...restProps }: TooltipTriggerProps) => {
+  return (
+    <TooltipPrimitive.Trigger asChild={asChild} {...restProps}>
+      {children}
+    </TooltipPrimitive.Trigger>
+  );
+};
+
+TooltipTrigger.displayName = 'Tooltip.Trigger';
+
+const TooltipContent = ({
+  children,
+  side = 'top',
+  sideOffset = 8,
+  collisionPadding = 0,
+  avoidCollisions = true,
+  ...restProps
+}: TooltipContentProps) => {
+  return (
+    <TooltipPrimitive.Portal>
+      <StyledTooltipContent
+        side={side}
+        sideOffset={sideOffset}
+        collisionPadding={collisionPadding}
+        avoidCollisions={avoidCollisions}
+        {...restProps}
+      >
+        {children}
+      </StyledTooltipContent>
+    </TooltipPrimitive.Portal>
+  );
+};
+
+TooltipContent.displayName = 'Tooltip.Content';
+
+export const Tooltip = {
+  Provider: TooltipPrimitive.Provider,
+  Root: TooltipRoot,
+  Trigger: TooltipTrigger,
+  Content: TooltipContent,
+};

packages/jds/src/components/Tooltip/index.ts

@@ -0,0 +1,2 @@
+export * from './Tooltip';
+export type { TooltipProps, TooltipTriggerProps, TooltipContentProps } from './tooltip.types';