@conscience-technology/ctds 0.3.3 → 0.3.4

package/assets/components/Checkbox/Checkbox.module.css

@@ -3,6 +3,7 @@
    시각 요소 = .indicator, 접근성 = 실제 <input type="checkbox"> (.visually-hidden).
    FilterButton type="checkbox"도 indicator를 재사용한다. */
 .root {
+  position: relative;
   display: inline-flex;
   align-items: center;
   gap: var(--space-2);

package/assets/components/MenuItem/MenuItem.module.css

@@ -41,13 +41,19 @@
    - grid → inline-flex center: 라벨/trailing이 사라진 상태에서 아이콘 정중앙 정렬
    - width = min-height: 완전한 정사각. 시각 폭이 rail 폭과 정합.
    - padding-inline·gap 제거: 정사각 안에 아이콘 하나만 놓이도록.
+   - align-self: center: flex-column rail(.menu-rail)처럼 cross-axis가 가로인 부모 안에서
+     item이 왼쪽으로 쏠리는 걸 방지. parent가 flex가 아니면 무해.
+   - margin-inline: auto: block/grid 부모(라벨 숨긴 Sidebar.Item 등)에서도 가로 중앙.
    - transition: width는 부모(Sidebar) 애니메이션과 짝지어져 자연스럽게. */
 .root[data-collapsed] {
   display: inline-flex;
+  align-items: center;
   justify-content: center;
   gap: 0;
   padding-inline: 0;
   width: var(--menu-item-h-md);
+  align-self: center;
+  margin-inline: auto;
 }
 .sm.root[data-collapsed] {
   width: var(--menu-item-h-sm);
@@ -135,8 +141,11 @@
 }
 .trailing {
   color: var(--fg-subtle);
-  /* trailing 자체는 라벨과 자연스러운 여백을 두되, 내부 첫 아이템은 margin 없음 */
-  margin-inline-start: var(--space-4);
+  /* 라벨 ↔ trailing 사이 여백은 root grid의 gap(--space-2)이 전담.
+     여기 margin-inline-start를 더 두면 trailing이 왼쪽으로 쏠려 보이고
+     라벨 ellipsis가 실제 trailing 폭보다 훨씬 일찍 걸린다 (라벨 1fr 트랙이
+     그만큼 좁아지므로). min-width:0은 trailing 안쪽 콘텐츠가 길어질 때
+     부모 1fr 트랙을 밀지 않도록 유지. */
   min-width: 0;
 }
 
@@ -200,13 +209,29 @@
   margin-inline-start: max(var(--menu-slot-gap), var(--half-overflow));
 }
 
-/* label */
+/* label — grid의 1fr 가운데 열. 긴 라벨은 ellipsis.
+   inline-flex가 아니라 block으로 두어야 text-overflow: ellipsis가 실제로 그려진다
+   (ellipsis는 블록 포매팅 컨텍스트의 line-box 끝에서만 생성). min-width:0 없이는
+   1fr 트랙이 콘텐츠 min-content로 터져 ellipsis가 안 걸리는 함정도 함께 방지. */
 .label {
-  display: inline-flex;
-  align-items: center;
+  display: block;
   min-width: 0;
   overflow: hidden;
   text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Tooltip 안 라벨 — 긴 문장은 자연스레 wrap. max-width로 2~3줄 안에 수렴.
+   Tooltip 콘텐츠는 기본이 nowrap(한 줄 유지)이라, 긴 메뉴 라벨이 뷰포트까지
+   쭉 뻗어 꼬리가 괴상하게 멀어진다. word-break는 CJK가 섞인 라벨에서
+   줄바꿈이 안 먹는 걸 보완. */
+.tooltipLabel {
+  display: block;
+  max-width: 22ch;
+  white-space: normal;
+  word-break: break-word;
+  overflow-wrap: anywhere;
+  line-height: var(--lh-tight);
 }
 
 /* 2줄 레이아웃 — description prop이 있을 때만 활성.

package/assets/components/MenuItem/MenuItem.tsx

@@ -5,6 +5,9 @@ import {
   cloneElement,
   forwardRef,
   isValidElement,
+  useCallback,
+  useEffect,
+  useRef,
   useState,
   type HTMLAttributes,
   type ReactElement,
@@ -14,6 +17,7 @@ import { Slot, Slottable } from "@radix-ui/react-slot";
 
 import { Icon } from "../Icon";
 import { Shortcut } from "../Shortcut";
+import { Tooltip } from "../Tooltip";
 import styles from "./MenuItem.module.css";
 
 export type MenuItemSize = "sm" | "md";
@@ -90,6 +94,20 @@ export type MenuItemProps = Omit<HTMLAttributes<HTMLDivElement>, "onClick"> & {
    */
   collapsed?: boolean;
 
+  /**
+   * true면 라벨이 ellipsis로 잘리거나 collapsed=true일 때 자동으로 Tooltip을 띄워
+   * 풀 라벨을 노출. Sidebar.Item처럼 좁은 폭이 상수인 사용처에서 유용.
+   *
+   * ⚠️ Dropdown/Context/Select/CommandPalette 어댑터(Radix Item + asChild) 안에서는
+   * 기본값 false 유지 — Radix의 asChild 체인 중간에 Tooltip이 끼면 포커스/하이라이트
+   * 라우팅과 포털 중첩이 꼬인다. 이 환경에서 Tooltip이 꼭 필요하면 사용처가
+   * MenuItem 바깥을 자체 Tooltip으로 감싸는 쪽이 안전.
+   *
+   * 라벨이 순수 텍스트(ReactNode에 요소가 섞이지 않음)일 때만 작동 — 복잡 ReactNode는
+   * Tooltip 콘텐츠를 안전하게 결정할 기준이 없어 무시.
+   */
+  truncateTooltip?: boolean;
+
   /**
    * root click 핸들러. leadingActions/trailingActions 내부 요소에서 발생한 클릭은
    * 자동으로 무시되지 않으므로, 하위 액션은 e.stopPropagation()을 스스로 호출해야 한다.
@@ -164,6 +182,24 @@ function firstCharOfChildren(children: ReactNode): string | null {
   return Array.from(trimmed)[0] ?? null;
 }
 
+/** children을 평탄화해 Tooltip 콘텐츠용 문자열로 환산. 순수 텍스트가 아니면 null.
+ *  (<Icon> 같은 요소가 섞인 커스텀 라벨에선 Tooltip을 띄우지 않음 — 어떤 텍스트로
+ *  보여줄지 결정할 안전한 기준이 없기 때문.) */
+function textFromChildren(children: ReactNode): string | null {
+  let text = "";
+  let onlyPlain = true;
+  Children.forEach(children, (child) => {
+    if (typeof child === "string" || typeof child === "number") {
+      text += String(child);
+    } else if (child != null && child !== false) {
+      onlyPlain = false;
+    }
+  });
+  if (!onlyPlain) return null;
+  const trimmed = text.trim();
+  return trimmed || null;
+}
+
 /** MenuItemAction을 { node, hoverOnly } 튜플로 정규화. */
 function normalizeAction(
   action: MenuItemAction,
@@ -235,7 +271,7 @@ const SectionHeader = forwardRef<HTMLDivElement, SectionHeaderProps>(
     if (!collapsible) {
       return (
         <div ref={ref} className={rootClass} role="presentation" {...rest}>
-          <span className={styles.label}>{children}</span>
+          <span className={styles.label} data-menuitem-label>{children}</span>
         </div>
       );
     }
@@ -264,7 +300,7 @@ const SectionHeader = forwardRef<HTMLDivElement, SectionHeaderProps>(
         }}
         {...rest}
       >
-        <span className={styles.label}>
+        <span className={styles.label} data-menuitem-label>
           {children}
           <Icon
             name="caret-down"
@@ -295,6 +331,7 @@ const MenuItem = forwardRef<HTMLDivElement, MenuItemProps>(
       disabled = false,
       asChild = false,
       collapsed = false,
+      truncateTooltip = false,
       collapsible = false,
       open: openProp,
       defaultOpen = true,
@@ -315,6 +352,31 @@ const MenuItem = forwardRef<HTMLDivElement, MenuItemProps>(
     const Comp = asChild ? Slot : "div";
     const iconSize = ICON_SIZE[size];
 
+    /* 라벨 ellipsis 감지 — label span의 scrollWidth > clientWidth면 잘린 상태.
+       잘렸을 때만 아래에서 Tooltip으로 감싸 풀 라벨 노출. truncateTooltip이 꺼진
+       사용처(Dropdown/Context/Select/CommandPalette 어댑터 등)에선 ResizeObserver를
+       아예 만들지 않아 CPU 비용도 들지 않음.
+       ref callback은 element 교체 시마다 ResizeObserver를 재부착. */
+    const [truncated, setTruncated] = useState(false);
+    const observerRef = useRef<ResizeObserver | null>(null);
+    const labelRefCallback = useCallback(
+      (node: HTMLSpanElement | null) => {
+        observerRef.current?.disconnect();
+        observerRef.current = null;
+        if (!truncateTooltip || !node) {
+          if (!node) setTruncated(false);
+          return;
+        }
+        const check = () => setTruncated(node.scrollWidth > node.clientWidth + 1);
+        check();
+        const ro = new ResizeObserver(check);
+        ro.observe(node);
+        observerRef.current = ro;
+      },
+      [truncateTooltip],
+    );
+    useEffect(() => () => observerRef.current?.disconnect(), []);
+
     /* leading: checked면 맨 앞에 자동 checkmark */
     const leadingComposed: MenuItemAction[] = checked
       ? [{ node: <Icon name="check" size={iconSize} />, key: "__check__" }, ...leadingActions]
@@ -414,7 +476,7 @@ const MenuItem = forwardRef<HTMLDivElement, MenuItemProps>(
       );
     }
 
-    return (
+    const node = (
       <Comp
         ref={ref}
         className={rootClass}
@@ -445,11 +507,11 @@ const MenuItem = forwardRef<HTMLDivElement, MenuItemProps>(
           !effectiveCollapsed &&
           (hasDescription ? (
             <span className={styles.labelStack}>
-              <span className={styles.label}>{children}</span>
+              <span className={styles.label} data-menuitem-label ref={labelRefCallback}>{children}</span>
               <span className={styles.description}>{description}</span>
             </span>
           ) : (
-            <span className={styles.label}>{children}</span>
+            <span className={styles.label} data-menuitem-label ref={labelRefCallback}>{children}</span>
           ))
         )}
         {hasTrailing && (
@@ -459,6 +521,25 @@ const MenuItem = forwardRef<HTMLDivElement, MenuItemProps>(
         )}
       </Comp>
     );
+
+    /* Tooltip 래핑 조건 — truncateTooltip이 켜진 경우에만 작동.
+       1) collapsed 상태: 라벨이 아이콘으로 수렴되어 보이지 않으므로 항상 풀 라벨을 띄움.
+       2) expanded + 라벨이 실제 ellipsis로 잘림: 중복 노출 없이 "안 보이는 부분만" 복원.
+       둘 다 children이 순수 텍스트일 때만 — 복잡 ReactNode 라벨은 Tooltip 콘텐츠로
+       무엇을 보일지 안전하게 결정할 기준이 없음. (asChild=링크 위임이어도 Tooltip은
+       MenuItem 바깥에서 감싸지므로 체인은 Tooltip → Slot → Link로 유지된다.)
+
+       side는 항상 right — 메뉴는 세로 리스트라 top/bottom으로 띄우면 바로 위/아래
+       아이템을 가린다. 뷰포트 끝에선 Radix가 자동 flip. */
+    const labelText = textFromChildren(children);
+    const shouldTooltip =
+      truncateTooltip && labelText != null && (effectiveCollapsed || truncated);
+    if (!shouldTooltip) return node;
+    return (
+      <Tooltip content={<span className={styles.tooltipLabel}>{labelText}</span>} side="right" sideOffset={8}>
+        {node}
+      </Tooltip>
+    );
   },
 );
 

package/assets/components/Radio/Radio.module.css

@@ -4,6 +4,7 @@
    같은 배경 레이어에 그려지므로 서브픽셀 어긋남이 없다). 접근성 = <input type="radio">.
    FilterButton type="radio"도 indicator를 재사용한다. */
 .root {
+  position: relative;
   display: inline-flex;
   align-items: center;
   gap: var(--space-2);

package/assets/components/Sidebar/Sidebar.tsx

@@ -272,6 +272,9 @@ const SidebarItem = forwardRef<HTMLDivElement, SidebarItemProps>(function Sideba
   const leadingActions: MenuItemAction[] = icon ? [icon] : [];
   const trailingActions: MenuItemAction[] = trailing ? [trailing] : [];
 
+  /* ellipsis 시 Tooltip, collapsed 시 항상 Tooltip은 MenuItem이 자체 처리.
+     children을 넘기면 복잡 ReactNode라 Tooltip이 안 뜰 수 있으므로, 평문 라벨만 있을 땐
+     label 문자열을 그대로 children으로 흘려 MenuItem이 안전하게 Tooltip 콘텐츠를 결정하게 함. */
   return (
     <MenuItem
       ref={ref}
@@ -280,13 +283,13 @@ const SidebarItem = forwardRef<HTMLDivElement, SidebarItemProps>(function Sideba
       disabled={disabled}
       asChild={asChild}
       collapsed={collapsed}
+      truncateTooltip
       leadingActions={leadingActions}
       trailingActions={trailingActions}
       shortcut={shortcut}
       hasSubmenu={hasSubmenu}
       onClick={onClick}
       aria-label={collapsed ? label : undefined}
-      title={collapsed ? label : undefined}
     >
       {children ?? label}
     </MenuItem>

package/assets/prompts/components/menu-item.md

@@ -82,6 +82,7 @@ type MenuItemAction =
   active={boolean}                       // 현재 페이지/선택 아이템 강조
   disabled={boolean}
   collapsed={boolean}                    // icon-only. leading 하나만 남기고 label/trailing/shortcut 전부 숨김. (Sidebar가 자동 주입)
+  truncateTooltip={boolean}              // 라벨이 …로 잘리거나 collapsed일 때 호버 Tooltip으로 풀 라벨 노출. Sidebar.Item 자동 ON. Dropdown/Context/Select 어댑터 안에선 Radix asChild 체인 꼬임 방지로 끄는 걸 권장.
   asChild={boolean}                      // Radix Slot — <Link>/<a>/DropdownMenu.Item 등에 위임
   onClick={(e) => void}
 />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conscience-technology/ctds",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "CTDS — 하이브리드 디자인 시스템 설치 · 온보딩 CLI (shadcn식 코드 생성기)",
   "type": "module",
   "sideEffects": [