@x-plat/design-system 0.7.1 → 0.8.0

package/dist/components/Tooltip/index.cjs

@@ -70,13 +70,15 @@ var clsx_default = clsx;
 // src/components/Tooltip/Tooltip.tsx
 var import_jsx_runtime2 = require("react/jsx-runtime");
 var OFFSET = 12;
+var GAP = 8;
 var SHOW_DELAY = 300;
 var Tooltip = (props) => {
   const {
-    type = "dark",
+    children,
     title,
     description,
-    children,
+    type = "dark",
+    follow = false,
     disabled = false
   } = props;
   const triggerRef = import_react2.default.useRef(null);
@@ -84,49 +86,91 @@ var Tooltip = (props) => {
   const [visible, setVisible] = import_react2.default.useState(false);
   const [pos, setPos] = import_react2.default.useState({ left: 0, top: 0 });
   const delayTimer = import_react2.default.useRef(0);
-  const calculatePos = import_react2.default.useCallback((clientX, clientY) => {
+  const rafRef = import_react2.default.useRef(0);
+  const cursor = import_react2.default.useRef(null);
+  const clamp = import_react2.default.useCallback((left, top, w, h) => {
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+    return {
+      left: Math.min(Math.max(GAP, left), Math.max(GAP, vw - w - GAP)),
+      top: Math.min(Math.max(GAP, top), Math.max(GAP, vh - h - GAP))
+    };
+  }, []);
+  const placeAtCursor = import_react2.default.useCallback((x, y) => {
     const el = tooltipRef.current;
     if (!el) return;
     const w = el.offsetWidth;
     const h = el.offsetHeight;
-    const vw = window.innerWidth;
-    let left = clientX + OFFSET;
-    let top = clientY - h - OFFSET;
-    if (left + w > vw - 8) left = clientX - w - OFFSET;
-    if (top < 8) top = clientY + OFFSET;
-    if (left < 8) left = 8;
-    setPos({ left, top });
-  }, []);
-  const handleMouseEnter = import_react2.default.useCallback(() => {
+    let left = x + OFFSET;
+    let top = y - h - OFFSET;
+    if (left + w > window.innerWidth - GAP) left = x - w - OFFSET;
+    if (top < GAP) top = y + OFFSET;
+    setPos(clamp(left, top, w, h));
+  }, [clamp]);
+  const placeAtTrigger = import_react2.default.useCallback(() => {
+    const el = tooltipRef.current;
+    const trigger = triggerRef.current;
+    if (!el || !trigger) return;
+    const w = el.offsetWidth;
+    const h = el.offsetHeight;
+    const rect = trigger.getBoundingClientRect();
+    let top = rect.top - h - GAP;
+    if (top < GAP) top = rect.bottom + GAP;
+    const left = rect.left + rect.width / 2 - w / 2;
+    setPos(clamp(left, top, w, h));
+  }, [clamp]);
+  const reposition = import_react2.default.useCallback(() => {
+    if (follow && cursor.current) {
+      placeAtCursor(cursor.current.x, cursor.current.y);
+    } else {
+      placeAtTrigger();
+    }
+  }, [follow, placeAtCursor, placeAtTrigger]);
+  const handleMouseEnter = import_react2.default.useCallback((e) => {
     if (disabled) return;
-    delayTimer.current = window.setTimeout(() => {
-      setVisible(true);
-    }, SHOW_DELAY);
+    cursor.current = { x: e.clientX, y: e.clientY };
+    delayTimer.current = window.setTimeout(() => setVisible(true), SHOW_DELAY);
   }, [disabled]);
   const handleMouseMove = import_react2.default.useCallback((e) => {
-    if (!visible) return;
-    calculatePos(e.clientX, e.clientY);
-  }, [visible, calculatePos]);
-  const handleMouseLeave = import_react2.default.useCallback(() => {
-    window.clearTimeout(delayTimer.current);
-    setVisible(false);
-  }, []);
-  const handleClick = import_react2.default.useCallback(() => {
+    cursor.current = { x: e.clientX, y: e.clientY };
+    if (!visible || !follow) return;
+    cancelAnimationFrame(rafRef.current);
+    rafRef.current = requestAnimationFrame(() => {
+      if (cursor.current) placeAtCursor(cursor.current.x, cursor.current.y);
+    });
+  }, [visible, follow, placeAtCursor]);
+  const close = import_react2.default.useCallback(() => {
     window.clearTimeout(delayTimer.current);
+    cancelAnimationFrame(rafRef.current);
     setVisible(false);
   }, []);
+  const handleMouseLeave = import_react2.default.useCallback(() => {
+    cursor.current = null;
+    close();
+  }, [close]);
   const handleFocus = import_react2.default.useCallback(() => {
     if (disabled) return;
+    cursor.current = null;
     setVisible(true);
   }, [disabled]);
-  const handleBlur = import_react2.default.useCallback(() => {
-    setVisible(false);
-  }, []);
   import_react2.default.useLayoutEffect(() => {
-    if (!visible || !triggerRef.current) return;
-    const rect = triggerRef.current.getBoundingClientRect();
-    calculatePos(rect.right, rect.top);
-  }, [visible, calculatePos]);
+    if (!visible) return;
+    reposition();
+  }, [visible, reposition]);
+  import_react2.default.useEffect(() => {
+    if (!visible || follow) return;
+    const onChange = () => placeAtTrigger();
+    window.addEventListener("scroll", onChange, true);
+    window.addEventListener("resize", onChange);
+    return () => {
+      window.removeEventListener("scroll", onChange, true);
+      window.removeEventListener("resize", onChange);
+    };
+  }, [visible, follow, placeAtTrigger]);
+  import_react2.default.useEffect(() => () => {
+    window.clearTimeout(delayTimer.current);
+    cancelAnimationFrame(rafRef.current);
+  }, []);
   if (!title && !description) return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children });
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
     "div",
@@ -136,15 +180,16 @@ var Tooltip = (props) => {
       onMouseEnter: handleMouseEnter,
       onMouseMove: handleMouseMove,
       onMouseLeave: handleMouseLeave,
-      onClick: handleClick,
+      onClick: close,
       onFocus: handleFocus,
-      onBlur: handleBlur,
+      onBlur: close,
       children: [
         children,
         visible && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(Portal_default, { children: /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
           "div",
           {
             ref: tooltipRef,
+            role: "tooltip",
             className: clsx_default("lib-xplat-tooltip", type),
             style: { position: "fixed", left: pos.left, top: pos.top },
             children: [

package/dist/components/Tooltip/index.d.cts

@@ -1,10 +1,18 @@
 import React from 'react';
 
 interface TooltipProps {
-    type?: "dark" | "light";
+    children: React.ReactNode;
     title?: React.ReactNode;
     description?: React.ReactNode;
-    children: React.ReactNode;
+    type?: "dark" | "light";
+    /**
+     * 커서를 따라다닌다. 기본값은 `false` — 트리거 요소 기준으로 고정된다
+     * (PopOver/Dropdown/Select 와 같은 방식).
+     *
+     * 넓은 영역 안에서 **가리키는 지점**이 의미를 가질 때만 켠다. 버튼이나
+     * 아이콘처럼 대상이 작은 경우는 고정이 읽기 편하다.
+     */
+    follow?: boolean;
     disabled?: boolean;
 }
 declare const Tooltip: React.FC<TooltipProps>;

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

@@ -1,10 +1,18 @@
 import React from 'react';
 
 interface TooltipProps {
-    type?: "dark" | "light";
+    children: React.ReactNode;
     title?: React.ReactNode;
     description?: React.ReactNode;
-    children: React.ReactNode;
+    type?: "dark" | "light";
+    /**
+     * 커서를 따라다닌다. 기본값은 `false` — 트리거 요소 기준으로 고정된다
+     * (PopOver/Dropdown/Select 와 같은 방식).
+     *
+     * 넓은 영역 안에서 **가리키는 지점**이 의미를 가질 때만 켠다. 버튼이나
+     * 아이콘처럼 대상이 작은 경우는 고정이 읽기 편하다.
+     */
+    follow?: boolean;
     disabled?: boolean;
 }
 declare const Tooltip: React.FC<TooltipProps>;

package/dist/components/Tooltip/index.js

@@ -34,13 +34,15 @@ var clsx_default = clsx;
 // src/components/Tooltip/Tooltip.tsx
 import { Fragment, jsx as jsx2, jsxs } from "react/jsx-runtime";
 var OFFSET = 12;
+var GAP = 8;
 var SHOW_DELAY = 300;
 var Tooltip = (props) => {
   const {
-    type = "dark",
+    children,
     title,
     description,
-    children,
+    type = "dark",
+    follow = false,
     disabled = false
   } = props;
   const triggerRef = React2.useRef(null);
@@ -48,49 +50,91 @@ var Tooltip = (props) => {
   const [visible, setVisible] = React2.useState(false);
   const [pos, setPos] = React2.useState({ left: 0, top: 0 });
   const delayTimer = React2.useRef(0);
-  const calculatePos = React2.useCallback((clientX, clientY) => {
+  const rafRef = React2.useRef(0);
+  const cursor = React2.useRef(null);
+  const clamp = React2.useCallback((left, top, w, h) => {
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+    return {
+      left: Math.min(Math.max(GAP, left), Math.max(GAP, vw - w - GAP)),
+      top: Math.min(Math.max(GAP, top), Math.max(GAP, vh - h - GAP))
+    };
+  }, []);
+  const placeAtCursor = React2.useCallback((x, y) => {
     const el = tooltipRef.current;
     if (!el) return;
     const w = el.offsetWidth;
     const h = el.offsetHeight;
-    const vw = window.innerWidth;
-    let left = clientX + OFFSET;
-    let top = clientY - h - OFFSET;
-    if (left + w > vw - 8) left = clientX - w - OFFSET;
-    if (top < 8) top = clientY + OFFSET;
-    if (left < 8) left = 8;
-    setPos({ left, top });
-  }, []);
-  const handleMouseEnter = React2.useCallback(() => {
+    let left = x + OFFSET;
+    let top = y - h - OFFSET;
+    if (left + w > window.innerWidth - GAP) left = x - w - OFFSET;
+    if (top < GAP) top = y + OFFSET;
+    setPos(clamp(left, top, w, h));
+  }, [clamp]);
+  const placeAtTrigger = React2.useCallback(() => {
+    const el = tooltipRef.current;
+    const trigger = triggerRef.current;
+    if (!el || !trigger) return;
+    const w = el.offsetWidth;
+    const h = el.offsetHeight;
+    const rect = trigger.getBoundingClientRect();
+    let top = rect.top - h - GAP;
+    if (top < GAP) top = rect.bottom + GAP;
+    const left = rect.left + rect.width / 2 - w / 2;
+    setPos(clamp(left, top, w, h));
+  }, [clamp]);
+  const reposition = React2.useCallback(() => {
+    if (follow && cursor.current) {
+      placeAtCursor(cursor.current.x, cursor.current.y);
+    } else {
+      placeAtTrigger();
+    }
+  }, [follow, placeAtCursor, placeAtTrigger]);
+  const handleMouseEnter = React2.useCallback((e) => {
     if (disabled) return;
-    delayTimer.current = window.setTimeout(() => {
-      setVisible(true);
-    }, SHOW_DELAY);
+    cursor.current = { x: e.clientX, y: e.clientY };
+    delayTimer.current = window.setTimeout(() => setVisible(true), SHOW_DELAY);
   }, [disabled]);
   const handleMouseMove = React2.useCallback((e) => {
-    if (!visible) return;
-    calculatePos(e.clientX, e.clientY);
-  }, [visible, calculatePos]);
-  const handleMouseLeave = React2.useCallback(() => {
-    window.clearTimeout(delayTimer.current);
-    setVisible(false);
-  }, []);
-  const handleClick = React2.useCallback(() => {
+    cursor.current = { x: e.clientX, y: e.clientY };
+    if (!visible || !follow) return;
+    cancelAnimationFrame(rafRef.current);
+    rafRef.current = requestAnimationFrame(() => {
+      if (cursor.current) placeAtCursor(cursor.current.x, cursor.current.y);
+    });
+  }, [visible, follow, placeAtCursor]);
+  const close = React2.useCallback(() => {
     window.clearTimeout(delayTimer.current);
+    cancelAnimationFrame(rafRef.current);
     setVisible(false);
   }, []);
+  const handleMouseLeave = React2.useCallback(() => {
+    cursor.current = null;
+    close();
+  }, [close]);
   const handleFocus = React2.useCallback(() => {
     if (disabled) return;
+    cursor.current = null;
     setVisible(true);
   }, [disabled]);
-  const handleBlur = React2.useCallback(() => {
-    setVisible(false);
-  }, []);
   React2.useLayoutEffect(() => {
-    if (!visible || !triggerRef.current) return;
-    const rect = triggerRef.current.getBoundingClientRect();
-    calculatePos(rect.right, rect.top);
-  }, [visible, calculatePos]);
+    if (!visible) return;
+    reposition();
+  }, [visible, reposition]);
+  React2.useEffect(() => {
+    if (!visible || follow) return;
+    const onChange = () => placeAtTrigger();
+    window.addEventListener("scroll", onChange, true);
+    window.addEventListener("resize", onChange);
+    return () => {
+      window.removeEventListener("scroll", onChange, true);
+      window.removeEventListener("resize", onChange);
+    };
+  }, [visible, follow, placeAtTrigger]);
+  React2.useEffect(() => () => {
+    window.clearTimeout(delayTimer.current);
+    cancelAnimationFrame(rafRef.current);
+  }, []);
   if (!title && !description) return /* @__PURE__ */ jsx2(Fragment, { children });
   return /* @__PURE__ */ jsxs(
     "div",
@@ -100,15 +144,16 @@ var Tooltip = (props) => {
       onMouseEnter: handleMouseEnter,
       onMouseMove: handleMouseMove,
       onMouseLeave: handleMouseLeave,
-      onClick: handleClick,
+      onClick: close,
       onFocus: handleFocus,
-      onBlur: handleBlur,
+      onBlur: close,
       children: [
         children,
         visible && /* @__PURE__ */ jsx2(Portal_default, { children: /* @__PURE__ */ jsxs(
           "div",
           {
             ref: tooltipRef,
+            role: "tooltip",
             className: clsx_default("lib-xplat-tooltip", type),
             style: { position: "fixed", left: pos.left, top: pos.top },
             children: [