@idbrnd/design-system 1.3.4 → 1.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @idbrnd/design-system
 
-![Version](https://img.shields.io/badge/version-1.3.4-4B5FE1?style=flat-square)
+![Version](https://img.shields.io/badge/version-1.4.0-4B5FE1?style=flat-square)
 ![React](https://img.shields.io/badge/React-18.3.1-61DAFB?style=flat-square&logo=react&logoColor=white)
 ![Vite](https://img.shields.io/badge/Vite-7.3.0-646CFF?style=flat-square&logo=vite&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.9.3-3178C6?style=flat-square&logo=typescript&logoColor=white)
@@ -55,6 +55,7 @@ export default function App() {
   - [Toast](#toast)
   - [Snackbar](#snackbar)
   - [PushBadge](#pushbadge)
+  - [Tooltip](#tooltip)
 - [Select](#select)
 - [Dropdown](#dropdown)
 - [Content](#content)
@@ -480,6 +481,66 @@ import { PushBadge } from "@idbrnd/design-system";
 | `count`       | `number`                          | —      | `variant="number"` 시 표시할 숫자 |
 | `customStyle` | `CSSProperties`                   | —      | 추가 인라인 스타일                |
 
+### Tooltip
+
+트리거 엘리먼트에 마우스를 올리거나 클릭하면 말풍선 형태의 안내 텍스트를 표시하는 컴포넌트입니다.
+
+```tsx
+import { Tooltip } from "@idbrnd/design-system";
+
+<Tooltip content="안녕하세요!" position="top">
+  <button>Hover me</button>
+</Tooltip>
+```
+
+**클릭 트리거 + render function**
+
+```tsx
+<Tooltip
+  trigger="click"
+  position="bottom"
+  content={(close) => (
+    <div>
+      <span>메시지를 작성해요.</span>
+      <button onClick={close}>닫기</button>
+    </div>
+  )}
+>
+  <button>Click me</button>
+</Tooltip>
+```
+
+**말줄임 시에만 표시**
+
+```tsx
+<Tooltip content="긴 텍스트 전체 내용" visibleOnEllipsis>
+  <span style={{ overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
+    긴 텍스트 전체 내용
+  </span>
+</Tooltip>
+```
+
+| Prop               | 타입                                                                                               | 기본값      | 설명                                                              |
+| ------------------ | -------------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------- |
+| `content`          | `ReactNode \| ((close: () => void) => ReactNode)`                                                  | —           | **(필수)** 툴팁에 표시할 내용. render function 전달 시 `close` 콜백 사용 가능 |
+| `trigger`          | `"hover"` \| `"click"`                                                                             | `"hover"`   | 트리거 방식                                                       |
+| `variant`          | `"default"` \| `"compact"`                                                                         | `"default"` | 크기 변형. default: 8px 12px, compact: 4px 12px                   |
+| `position`         | `"top"` \| `"top-left"` \| `"top-right"` \| `"bottom"` \| `"bottom-left"` \| `"bottom-right"` \| `"left"` \| `"left-top"` \| `"left-bottom"` \| `"right"` \| `"right-top"` \| `"right-bottom"` | `"top"` | 툴팁 표시 위치 (12방향) |
+| `arrow`            | `boolean`                                                                                          | `true`      | 화살표(꼬리표) 표시 여부                                          |
+| `as`               | `keyof JSX.IntrinsicElements`                                                                      | `"span"`    | 트리거 래퍼 HTML 태그                                             |
+| `visibleOnEllipsis`| `boolean`                                                                                          | `false`     | `true` 시 자식에 말줄임이 발생했을 때만 툴팁 표시                 |
+| `backgroundColor`  | `string`                                                                                           | —           | 툴팁 배경색 커스터마이징                                          |
+| `contentColor`     | `string`                                                                                           | —           | 툴팁 텍스트 색상 커스터마이징                                     |
+| `customStyle`      | `CSSProperties`                                                                                    | —           | 툴팁 박스에 적용할 추가 인라인 스타일                             |
+| `children`         | `ReactNode`                                                                                        | —           | **(필수)** 툴팁을 트리거할 자식 엘리먼트                          |
+
+유의사항:
+
+- `trigger="click"` 시 외부 클릭, 스크롤, 리사이즈 시 자동으로 닫힙니다.
+- `position`의 첫 번째 단어는 툴팁이 놓이는 방향, 두 번째 단어는 화살표가 치우치는 방향입니다.
+- `content`에 render function을 전달하면 닫기 버튼 등 인터랙션을 구현할 수 있습니다.
+- 툴팁은 `document.body`에 포탈로 렌더링됩니다.
+
 ---
 
 ## Select
@@ -506,7 +567,7 @@ function SelectExample() {
       heading="과일 선택"
       placeholder="선택해주세요."
       options={options}
-      value={selected}
+      selectedValue={selected}
       onSelect={setSelected}
     />
   );
@@ -544,7 +605,7 @@ function SelectExample() {
 | Prop             | 타입                                                     | 기본값            | 설명                                                          |
 | ---------------- | -------------------------------------------------------- | ----------------- | ------------------------------------------------------------- |
 | `options`        | `DropdownOption[]`                                       | `[]`              | 드롭다운에 표시할 옵션 배열. `{ label, value, icon? }` 형태   |
-| `value`          | `DropdownOption \| null`                                 | —                 | 현재 선택된 옵션                                              |
+| `selectedValue`  | `DropdownOption \| null`                                 | —                 | 현재 선택된 옵션                                              |
 | `onSelect`       | `(option: DropdownOption) => void`                       | —                 | 옵션 선택 시 호출되는 콜백                                    |
 | `variant`        | `"default"` \| `"choosing"` \| `"error"` \| `"selected"` | `"default"`       | 트리거 상태. `choosing`/`selected`는 자동 적용                |
 | `size`           | `"large"` \| `"medium"` \| `"small"`                     | `"medium"`        | 트리거 높이. large: 44px, medium: 40px, small: 36px           |
@@ -778,6 +839,11 @@ import type {
   ToggleSwitchSize,
   ToastShowOptions,
   SnackbarShowOptions,
+  TooltipProps,
+  TooltipPosition,
+  TooltipVariant,
+  TooltipTrigger,
+  TooltipContent,
   ContentBadgeProps,
   ContentBadgeVariant,
   ContentBadgeSize,

package/dist/components/Select/Select.d.ts

@@ -1,4 +1,4 @@
 import type { SelectProps } from './Select.types';
 export type { SelectAlign, SelectProps, SelectSize, SelectType, SelectVariant, } from './Select.types';
-declare function Select({ variant, size, heading, required, leadingContent, description, disabled, placeholder, value, onSelect, options, type, align, content, buttonWidth, descriptionWidth, customStyle, textColor, }: SelectProps): import("react/jsx-runtime").JSX.Element;
+declare function Select({ variant, size, heading, required, leadingContent, description, disabled, placeholder, selectedValue, onSelect, options, type, align, content, buttonWidth, descriptionWidth, customStyle, textColor, }: SelectProps): import("react/jsx-runtime").JSX.Element;
 export default Select;

package/dist/components/Select/Select.types.d.ts

@@ -44,7 +44,7 @@ export interface SelectProps {
      */
     placeholder?: ReactNode;
     /** 현재 선택된 옵션. */
-    value?: DropdownOption | null;
+    selectedValue?: DropdownOption | null;
     /** 옵션 선택 시 콜백. */
     onSelect?: (option: DropdownOption) => void;
     /** 드롭다운 옵션 목록. (기본값: 빈 배열) */

package/dist/components/Tooltip/Tooltip.d.ts

@@ -0,0 +1,10 @@
+import type { TooltipProps, TooltipState } from './Tooltip.types';
+export interface TooltipPortalProps {
+    tooltip: TooltipState | null;
+    backgroundColor?: string;
+    contentColor?: string;
+}
+export declare function TooltipPortal({ tooltip, backgroundColor, contentColor }: TooltipPortalProps): import("react").ReactPortal | null;
+declare function Tooltip({ content, trigger, variant, position, arrow, as, visibleOnEllipsis, // 자식 엘리먼트에 말줄임(ellipsis)이 발생했을 때만 툴팁을 표시.
+backgroundColor, contentColor, customStyle, children, }: TooltipProps): import("react/jsx-runtime").JSX.Element;
+export default Tooltip;

package/dist/components/Tooltip/Tooltip.types.d.ts

@@ -0,0 +1,97 @@
+import type { CSSProperties, ReactNode } from 'react';
+/**
+ * 툴팁이 표시될 위치 (12방향).
+ *
+ * 첫 번째 단어 = 툴팁이 놓이는 방향
+ * 두 번째 단어 = 화살표가 치우치는 방향
+ *
+ * @example
+ * 'top'          → 트리거 위 중앙
+ * 'top-left'     → 트리거 위, 왼쪽 정렬
+ * 'right-bottom' → 트리거 오른쪽, 아래 정렬
+ */
+export type TooltipPosition = 'top-left' | 'top' | 'top-right' | 'right-top' | 'right' | 'right-bottom' | 'bottom-left' | 'bottom' | 'bottom-right' | 'left-top' | 'left' | 'left-bottom';
+/**
+ * 툴팁 크기 변형.
+ * - `'default'` : 넉넉한 패딩 (8px 12px)
+ * - `'compact'` : 작은 패딩   (4px 12px)
+ */
+export type TooltipVariant = 'default' | 'compact';
+/**
+ * 툴팁 트리거 방식.
+ * - `'hover'` : 마우스를 올리면 표시, 벗어나면 숨김
+ * - `'click'` : 클릭하면 토글, 외부 클릭 시 숨김
+ */
+export type TooltipTrigger = 'hover' | 'click';
+/**
+ * 툴팁 콘텐츠 타입.
+ *
+ * - `ReactNode` — 단순 텍스트나 JSX를 바로 전달
+ * - `(close) => ReactNode` — 툴팁을 닫는 `close` 콜백을 받는 render function.
+ *   닫기 버튼이나 액션 버튼 등 인터랙션이 필요할 때 사용.
+ *
+ * @example
+ * // 단순 텍스트
+ * content="안녕하세요"
+ *
+ * // render function — 닫기 버튼 + 액션
+ * content={(close) => (
+ *   <div>
+ *     <span>메시지</span>
+ *     <button onClick={close}>닫기</button>
+ *   </div>
+ * )}
+ */
+export type TooltipContent = ReactNode | ((close: () => void) => ReactNode);
+export interface TooltipProps {
+    /**
+     * 툴팁에 표시할 내용.
+     * 문자열·JSX를 직접 전달하거나, `(close) => ReactNode` 형태의 render function을 전달.
+     */
+    content: TooltipContent;
+    /**
+     * 트리거 방식.
+     * @default 'hover'
+     */
+    trigger?: TooltipTrigger;
+    /**
+     * 크기 변형.
+     * @default 'default'
+     */
+    variant?: TooltipVariant;
+    /**
+     * 툴팁이 표시될 위치 (12방향).
+     * @default 'top'
+     */
+    position?: TooltipPosition;
+    /**
+     * 화살표(꼬리표) 표시 여부.
+     * @default true
+     */
+    arrow?: boolean;
+    /**
+     * 트리거를 감싸는 래퍼 HTML 태그.
+     * 기본값은 `'span'`. 테이블 셀 등에서는 `'td'`, `'div'` 등으로 변경.
+     * @default 'span'
+     */
+    as?: keyof JSX.IntrinsicElements;
+    /**
+     * `true`이면 자식 엘리먼트에 말줄임(ellipsis)이 발생했을 때만 툴팁을 표시.
+     * @default false
+     */
+    visibleOnEllipsis?: boolean;
+    /** 툴팁 배경색 커스터마이징. 미지정 시 디자인 토큰 기본색 사용. */
+    backgroundColor?: string;
+    /** 툴팁 텍스트·아이콘 색상 커스터마이징. 미지정 시 디자인 토큰 기본색 사용. */
+    contentColor?: string;
+    /** 툴팁 박스에 적용할 추가 인라인 스타일. */
+    customStyle?: CSSProperties;
+    /** 툴팁을 트리거할 자식 엘리먼트. */
+    children: ReactNode;
+}
+/** 내부용 — useTooltip hook이 관리하는 툴팁 상태. */
+export interface TooltipState {
+    content: ReactNode;
+    rect: DOMRect;
+    position: TooltipPosition;
+}

package/dist/components/Tooltip/useTooltip.d.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+import type { TooltipPosition, TooltipState } from './Tooltip.types';
+export declare function calcTooltipPosition(rect: DOMRect, tooltipEl: HTMLDivElement, position: TooltipPosition): {
+    top: number;
+    left: number;
+};
+export declare function useTooltip(): {
+    readonly tooltip: TooltipState | null;
+    readonly showTooltip: (el: HTMLElement, content: ReactNode, position: TooltipPosition) => void;
+    readonly hideTooltip: () => void;
+};

package/dist/index.d.ts

@@ -40,3 +40,5 @@ export { default as Select } from "./components/Select/Select";
 export type { SelectProps, SelectVariant, SelectSize, SelectType, SelectAlign, } from "./components/Select/Select";
 export { default as Dropdown } from "./components/Dropdown/Dropdown";
 export type { DropdownProps, DropdownType, DropdownAlign, DropdownOption, } from "./components/Dropdown/Dropdown.types";
+export { default as Tooltip } from "./components/Tooltip/Tooltip";
+export type { TooltipProps, TooltipPosition, TooltipVariant, TooltipTrigger, TooltipContent, } from "./components/Tooltip/Tooltip.types";