@rencar-dev/feature-modules-public 0.0.7 → 1.1.0

package/README.md

@@ -10,206 +10,101 @@ npm install @rencar-dev/feature-modules-public
 yarn add @rencar-dev/feature-modules-public
 ```
 
-## 사용법
+## 모듈 목록
 
-```typescript
-// hooks 모듈 가져오기
-import { useExample } from "@rencar-dev/feature-modules-public/hooks";
-
-function MyComponent() {
-  const { count, increment, decrement, reset } = useExample(0);
-
-  return (
-    <div>
-      <p>Count: {count}</p>
-      <button onClick={increment}>+</button>
-      <button onClick={decrement}>-</button>
-      <button onClick={reset}>Reset</button>
-    </div>
-  );
-}
-```
-
-## Presence 모듈
-
-실시간 사용자 프레즌스(현재 접속자) 기능을 위한 모듈입니다.
-
-### Socket 초기화
-
-프레즌스 훅을 사용하기 전에 반드시 소켓을 초기화해야 합니다.
-
-#### initPresenceSocket
-
-소켓 연결을 설정합니다. **앱 시작 시 1회 호출**해야 합니다.
-
-```tsx
-import { initPresenceSocket } from "@rencar-dev/feature-modules-public/presence";
-
-// 앱 초기화 시 (예: App.tsx 또는 index.tsx)
-initPresenceSocket({
-  url: "https://your-socket-server.com",
-  transports: ["websocket"], // 선택사항, 기본값: ["websocket"]
-});
-```
-
-**PresenceConfig:**
-
-| 옵션         | 타입                           | 필수 | 기본값          | 설명          |
-| ------------ | ------------------------------ | ---- | --------------- | ------------- |
-| `url`        | `string`                       | ✅   | -               | 소켓 서버 URL |
-| `transports` | `("websocket" \| "polling")[]` | -    | `["websocket"]` | 전송 방식     |
-
----
-
-#### getPresenceSocket
-
-공유 소켓 인스턴스를 반환합니다. 초기화되지 않은 경우 에러를 발생시킵니다.
-
-```tsx
-import { getPresenceSocket } from "@rencar-dev/feature-modules-public/presence";
-
-const socket = getPresenceSocket();
-socket.emit("custom-event", { data: "example" });
-```
-
----
-
-#### disconnectPresenceSocket
-
-소켓 연결을 종료하고 정리합니다. 앱 종료 시 또는 로그아웃 시 호출할 수 있습니다.
+| 모듈     | 설명                   | 문서                                 |
+| -------- | ---------------------- | ------------------------------------ |
+| hooks    | 유틸리티 React 훅      | [docs/hooks.md](docs/hooks.md)       |
+| presence | 실시간 접속자 프레즌스 | [docs/presence.md](docs/presence.md) |
 
 ```tsx
-import { disconnectPresenceSocket } from "@rencar-dev/feature-modules-public/presence";
+// hooks 모듈 import
+import { useExample } from "@rencar-dev/feature-modules-public/hooks";
 
-// 로그아웃 시
-function handleLogout() {
-  disconnectPresenceSocket();
-  // ... 기타 로그아웃 로직
-}
+// presence 모듈 import
+import {
+  usePresence,
+  PresenceFloating,
+} from "@rencar-dev/feature-modules-public/presence";
+import "@rencar-dev/feature-modules-public/presence/styles.css";
 ```
 
 ---
 
-#### isPresenceSocketInitialized
+## 개발 가이드
 
-소켓 초기화 여부를 확인합니다.
+### 로컬 개발
 
-```tsx
-import { isPresenceSocketInitialized } from "@rencar-dev/feature-modules-public/presence";
+```bash
+# 개발 모드 (watch)
+npm run dev
 
-if (!isPresenceSocketInitialized()) {
-  initPresenceSocket({ url: "..." });
-}
+# 빌드
+npm run build
 ```
 
----
+### 새 모듈 추가하기
 
-## Presence Hooks
+1. **폴더 생성**: `src/[모듈명]/` 폴더 생성
+2. **Entry 파일**: `src/[모듈명]/index.ts` 생성 및 export 정의
+3. **tsup 설정**: `tsup.config.ts`에 entry 추가
 
-실시간 사용자 프레즌스(현재 접속자) 기능을 위한 훅입니다.
+   ```ts
+   entry: {
+     "hooks/index": "src/hooks/index.ts",
+     "presence/index": "src/presence/index.ts",
+     "[모듈명]/index": "src/[모듈명]/index.ts",  // 추가
+   },
+   ```
 
-### usePresence
+4. **package.json exports 추가**:
 
-특정 룸에 참여하고 해당 룸의 사용자 목록을 추적합니다. 현재 사용자가 해당 룸에 참여자로 등록됩니다.
+   ```json
+   "./[모듈명]": {
+     "types": "./dist/[모듈명]/index.d.ts",
+     "import": "./dist/[모듈명]/index.js",
+     "require": "./dist/[모듈명]/index.cjs"
+   }
+   ```
 
-**Options:**
+5. **typesVersions 추가**:
 
-| 옵션                | 타입           | 필수 | 기본값          | 설명                                               |
-| ------------------- | -------------- | ---- | --------------- | -------------------------------------------------- |
-| `roomId`            | `string`       | ✅   | -               | 참여할 룸 ID                                       |
-| `currentUser`       | `PresenceUser` | ✅   | -               | 현재 사용자 정보 (`{ userId, name, ...추가속성 }`) |
-| `enabled`           | `boolean`      | -    | `true`          | 훅 활성화 여부                                     |
-| `heartbeatInterval` | `number`       | -    | `600000` (10분) | 하트비트 간격 (ms)                                 |
+   ```json
+   "[모듈명]": ["./dist/[모듈명]/index.d.ts"]
+   ```
 
-**Returns:** `PresenceUser[]` - 현재 룸에 있는 사용자 목록
+6. **문서 작성**: `docs/[모듈명].md` 생성
+7. **README 업데이트**: 모듈 목록 테이블에 추가
 
-**사용 예시:**
+### 배포
 
-```tsx
-import { usePresence } from "@rencar-dev/feature-modules-public/presence";
-
-function MyPage() {
-  const users = usePresence({
-    roomId: "my-app:page-123",
-    currentUser: { userId: "1", name: "John Doe" },
-  });
-
-  return (
-    <div>
-      <p>현재 접속자: {users.length}명</p>
-      <ul>
-        {users.map((user) => (
-          <li key={user.userId}>{user.name}</li>
-        ))}
-      </ul>
-    </div>
-  );
-}
-```
+**자동 배포 (권장):**
 
-**조건부 활성화:**
+`master` 브랜치에 push하면 semantic-release가 자동으로:
 
-```tsx
-// 로그인한 경우에만 프레즌스 활성화
-const users = usePresence({
-  roomId: "my-room",
-  currentUser: { userId: user.id, name: user.name },
-  enabled: isLoggedIn,
-});
-```
+1. 커밋 메시지 분석 (`fix:`, `feat:` 등)
+2. 버전 번호 결정 및 package.json 업데이트
+3. Git 태그 생성
+4. npm 배포
+5. GitHub Release 생성
 
----
-
-### usePresenceWatch
-
-여러 룸을 **참여 없이** 관찰(watch)합니다. 읽기 전용으로 다른 룸들의 접속자를 모니터링할 때 사용합니다.
+| 커밋 접두사 | 버전 변경     | 예시                     |
+| ----------- | ------------- | ------------------------ |
+| `fix:`      | patch (0.0.X) | `fix: 버그 수정`         |
+| `feat:`     | minor (0.X.0) | `feat: 새 기능 추가`     |
+| `feat!:`    | major (X.0.0) | `feat!: breaking change` |
 
-**Options:**
+> **Note**: `chore:`, `docs:`, `style:` 등은 릴리즈를 트리거하지 않습니다.
 
-| 옵션      | 타입       | 필수 | 기본값 | 설명              |
-| --------- | ---------- | ---- | ------ | ----------------- |
-| `roomIds` | `string[]` | ✅   | -      | 관찰할 룸 ID 배열 |
-| `enabled` | `boolean`  | -    | `true` | 훅 활성화 여부    |
+**수동 배포:**
 
-**Returns:** `Record<string, PresenceUser[]>` - 룸 ID → 사용자 목록 맵
-
-**사용 예시:**
-
-```tsx
-import { usePresenceWatch } from "@rencar-dev/feature-modules-public/presence";
-
-function Dashboard() {
-  const roomsUsers = usePresenceWatch({
-    roomIds: ["page-1", "page-2", "page-3"],
-  });
-
-  return (
-    <div>
-      {Object.entries(roomsUsers).map(([roomId, users]) => (
-        <div key={roomId}>
-          <h3>{roomId}</h3>
-          <p>{users.length}명 접속 중</p>
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
-**동적 룸 ID:**
-
-```tsx
-// 룸 ID가 변경되면 자동으로 watch/unwatch 처리
-const [selectedRooms, setSelectedRooms] = useState(["room-a"]);
-const roomsUsers = usePresenceWatch({ roomIds: selectedRooms });
+```bash
+npm version patch  # 또는 minor, major
+npm publish
 ```
 
 ---
 
-### usePresence vs usePresenceWatch 비교
+## 라이선스
 
-| 항목        | usePresence                      | usePresenceWatch              |
-| ----------- | -------------------------------- | ----------------------------- |
-| **룸 참여** | ✅ 참여함 (다른 사용자에게 보임) | ❌ 참여 안함 (관찰만)         |
-| **룸 개수** | 1개                              | 여러 개                       |
-| **용도**    | 현재 페이지 접속자 표시          | 대시보드에서 여러 룸 모니터링 |
+MIT

package/dist/presence/index.cjs

@@ -20,6 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/presence/index.ts
 var presence_exports = {};
 __export(presence_exports, {
+  PresenceAvatars: () => PresenceAvatars,
+  PresenceFloating: () => PresenceFloating,
   disconnectPresenceSocket: () => disconnectPresenceSocket,
   getPresenceSocket: () => getPresenceSocket,
   initPresenceSocket: () => initPresenceSocket,
@@ -243,7 +245,7 @@ function usePresenceAvatarsState(options) {
   const [hoveredIndex, setHoveredIndex] = (0, import_react3.useState)(null);
   const hoveredUser = hoveredIndex != null ? visibleUsers[hoveredIndex] : null;
   const baseTopZ = visibleUsers.length + 1;
-  const getInitial = (0, import_react3.useCallback)((user) => {
+  const getInitial2 = (0, import_react3.useCallback)((user) => {
     return getInitialFromUser(user);
   }, []);
   const getZIndex = (0, import_react3.useCallback)(
@@ -258,7 +260,7 @@ function usePresenceAvatarsState(options) {
     hoveredUser,
     hoveredIndex,
     setHoveredIndex,
-    getInitial,
+    getInitial: getInitial2,
     getZIndex
   };
 }
@@ -445,8 +447,234 @@ function usePresenceFloatingState(options) {
     onAvatarLeave
   };
 }
+
+// src/presence/components/PresenceAvatars.tsx
+var import_react5 = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+function PresenceAvatars({
+  users,
+  maxVisible = 3,
+  className,
+  renderAvatar,
+  renderTooltip,
+  renderMore
+}) {
+  const {
+    visibleUsers,
+    moreCount,
+    hoveredUser,
+    hoveredIndex,
+    setHoveredIndex,
+    getInitial: getInitial2,
+    getZIndex
+  } = usePresenceAvatarsState({ users, maxVisible });
+  const [tooltipPos, setTooltipPos] = (0, import_react5.useState)(null);
+  const updateTooltipPos = (0, import_react5.useCallback)((el) => {
+    const rect = el.getBoundingClientRect();
+    const tooltipWidth = 200;
+    const half = tooltipWidth / 2;
+    const centerX = rect.left + rect.width / 2;
+    const left = Math.min(
+      Math.max(centerX, half + 8),
+      window.innerWidth - half - 8
+    );
+    const top = Math.min(rect.bottom + 8, window.innerHeight - 8);
+    setTooltipPos({ top, left });
+  }, []);
+  const handleMouseEnter = (0, import_react5.useCallback)(
+    (e, idx) => {
+      setHoveredIndex(idx);
+      updateTooltipPos(e.currentTarget);
+    },
+    [setHoveredIndex, updateTooltipPos]
+  );
+  const handleMouseLeave = (0, import_react5.useCallback)(() => {
+    setHoveredIndex(null);
+  }, [setHoveredIndex]);
+  const defaultTooltipRenderer = (0, import_react5.useCallback)(
+    ({ user, position }) => /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+      "div",
+      {
+        className: "presence-avatars__tooltip",
+        style: { top: position.top, left: position.left },
+        children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "presence-avatars__tooltip-row", children: [
+            /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "presence-avatars__tooltip-key", children: "Name" }),
+            /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "presence-avatars__tooltip-val", children: user.name || "-" })
+          ] }),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "presence-avatars__tooltip-row", children: [
+            /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "presence-avatars__tooltip-key", children: "ID" }),
+            /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "presence-avatars__tooltip-val", children: user.userId || "-" })
+          ] })
+        ]
+      }
+    ),
+    []
+  );
+  const defaultAvatarRenderer = (0, import_react5.useCallback)(
+    ({ initial, isHovered }) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: initial }),
+    []
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: `presence-avatars ${className ?? ""}`, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "presence-avatars__stack", children: [
+      visibleUsers.map((user, idx) => {
+        const isHovered = hoveredIndex === idx;
+        const initial = getInitial2(user);
+        const zIndex = getZIndex(idx, isHovered);
+        const renderProps = {
+          user,
+          index: idx,
+          initial,
+          isHovered,
+          zIndex
+        };
+        return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "span",
+          {
+            className: `presence-avatars__avatar ${isHovered ? "is-hovered" : ""}`,
+            style: { zIndex },
+            onMouseEnter: (e) => handleMouseEnter(e, idx),
+            onMouseLeave: handleMouseLeave,
+            "aria-label": user.name || user.userId || "",
+            children: renderAvatar ? renderAvatar(renderProps) : defaultAvatarRenderer(renderProps)
+          },
+          `${user.userId}-${idx}`
+        );
+      }),
+      moreCount > 0 && (renderMore ? renderMore(moreCount) : /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", { className: "presence-avatars__more", children: [
+        "+",
+        moreCount
+      ] }))
+    ] }),
+    hoveredUser && tooltipPos && (renderTooltip ? renderTooltip({ user: hoveredUser, position: tooltipPos }) : defaultTooltipRenderer({
+      user: hoveredUser,
+      position: tooltipPos
+    }))
+  ] });
+}
+
+// src/presence/components/PresenceFloating.tsx
+var import_react6 = require("react");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+function getInitial(user) {
+  const base = (user?.name || user?.userId || "").trim();
+  if (!base) return "?";
+  const ch = base.charAt(0);
+  return /[a-z]/i.test(ch) ? ch.toUpperCase() : ch;
+}
+function PresenceFloating({
+  users,
+  maxVisible = 8,
+  className,
+  style,
+  initialPosition,
+  title = "\uC5F4\uB78C\uC911",
+  emptyText = "\uC5C6\uC74C",
+  moreText = (n) => `+${n}\uBA85`,
+  renderAvatar,
+  renderTooltip
+}) {
+  const {
+    containerRef,
+    inlineStyle,
+    isDragging,
+    visibleUsers,
+    moreCount,
+    hoveredUser,
+    tooltipTop,
+    onMouseDownHeader,
+    onTouchStartHeader,
+    onAvatarEnter,
+    onAvatarLeave
+  } = usePresenceFloatingState({ users, maxVisible, initialPosition });
+  const defaultTooltipRenderer = (0, import_react6.useCallback)(
+    ({ user, top }) => /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
+      "div",
+      {
+        className: "presence-floating__tooltip",
+        style: { top: Math.max(0, top - 6) },
+        onMouseLeave: onAvatarLeave,
+        children: [
+          /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "presence-floating__tooltip-row", children: [
+            /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "presence-floating__tooltip-key", children: "Name" }),
+            /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "presence-floating__tooltip-val", children: user.name || "-" })
+          ] }),
+          /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "presence-floating__tooltip-row", children: [
+            /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "presence-floating__tooltip-key", children: "ID" }),
+            /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "presence-floating__tooltip-val", children: user.userId || "-" })
+          ] })
+        ]
+      }
+    ),
+    [onAvatarLeave]
+  );
+  const defaultAvatarRenderer = (0, import_react6.useCallback)(
+    ({ initial }) => /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children: initial }),
+    []
+  );
+  const combinedStyle = {
+    ...inlineStyle,
+    ...style
+  };
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
+    "div",
+    {
+      ref: containerRef,
+      className: `presence-floating ${isDragging ? "is-dragging" : ""} ${className ?? ""}`,
+      style: combinedStyle,
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
+          "div",
+          {
+            className: "presence-floating__header",
+            onMouseDown: onMouseDownHeader,
+            onTouchStart: onTouchStartHeader,
+            children: [
+              /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+                "span",
+                {
+                  className: "presence-floating__title",
+                  title,
+                  "aria-label": title,
+                  children: title
+                }
+              ),
+              /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "presence-floating__count", children: users.length })
+            ]
+          }
+        ),
+        hoveredUser && (renderTooltip ? renderTooltip({ user: hoveredUser, top: tooltipTop }) : defaultTooltipRenderer({ user: hoveredUser, top: tooltipTop })),
+        /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "presence-floating__body", children: [
+          visibleUsers.length === 0 ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "presence-floating__empty", children: emptyText }) : visibleUsers.map((user, idx) => {
+            const initial = getInitial(user);
+            const label = user.name || user.userId || "";
+            const renderProps = {
+              user,
+              initial
+            };
+            return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+              "span",
+              {
+                className: "presence-floating__avatar",
+                title: label,
+                "aria-label": label,
+                onMouseEnter: (e) => onAvatarEnter(e, user),
+                onMouseLeave: onAvatarLeave,
+                children: renderAvatar ? renderAvatar(renderProps) : defaultAvatarRenderer(renderProps)
+              },
+              `${user.userId}-${idx}`
+            );
+          }),
+          moreCount > 0 && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "presence-floating__more", children: moreText(moreCount) })
+        ] })
+      ]
+    }
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  PresenceAvatars,
+  PresenceFloating,
   disconnectPresenceSocket,
   getPresenceSocket,
   initPresenceSocket,