@conscience-technology/ctds 0.3.3 → 0.4.0

package/assets/components/ListItem/ListItem.tsx

@@ -1,201 +1,102 @@
 "use client";
 
 /**
- * ListItem — 앞에 아바타/아이콘이 달린 리스트 한 줄 단위. 피드·알림·인박스·활동 로그를 포괄.
+ * ListItem — 3구역(leading / content / trailing) 고정 뼈대 + content 내부 자유 조립.
  *
- * anatomy 고정: [leading] [from (body | verb+target+surface)] [meta/trailing] [hoverActions]
- * 자체 chrome(border/padding/bg) 없음 — 리스트 분리는 부모 레이아웃이 담당.
+ * 축:
+ *   size       — 세로 여백감. md(기본, 작업/자원 리스트 밀도) | sm (활동 로그·알림 스트림 타이트)
+ *   align      — leading 세로 정렬. center(기본) | top (2줄 이상 본문용)
+ *   interactive — hover/focus 피드백 (href 또는 onClick 있을 때 자동)
  *
- * 서술 모드 배타:
- *   (A) body            — "회계팀 — 외주비 결재 요청"
- *   (B) verb+target     — "박지훈 · 댓글 남김 · ERP 2.0 사이드바"
+ * chrome 없음 — bg·border·radius 자체 공급 X. 리스트 분리는 부모가 담당.
+ * 블록 외형(배경·테두리로 상태 신호)이 필요하면 Callout 사용.
  *
- * variant는 default만 바꾼다 (anatomy는 공통):
- *   activity      — 과거 서술. unread false 기본
- *   notification  — 처리 필요. unread true 기본
- *   mention       — 멘션/댓글. unread true 기본
- *   system        — 사람 아닌 서비스 이벤트
+ * content 안에서 쓰는 subcomponents:
+ *   ListItem.Title        메인 제목 (앞에 Badge 등 inline 자유)
+ *   ListItem.Description  muted 서브 텍스트
+ *   ListItem.Meta         하단 meta 라인 (타임스탬프·상태)
+ *   ListItem.MetaDivider  hairline 세로 구분자
+ *
+ * 일정·이벤트처럼 날짜가 leading 아이덴티티인 자리는 [[EventListItem]] 사용.
  */
 
 import {
-  Children,
-  cloneElement,
   forwardRef,
-  isValidElement,
   type AnchorHTMLAttributes,
   type HTMLAttributes,
-  type ReactElement,
   type ReactNode,
   type Ref,
 } from "react";
-import { Slot } from "@radix-ui/react-slot";
 
 import styles from "./ListItem.module.css";
 
-export type ListItemVariant = "activity" | "notification" | "mention" | "system";
-export type ListItemLayout = "inline" | "stacked";
+export type ListItemSize = "sm" | "md";
+export type ListItemAlign = "center" | "top";
 
 type Common = {
-  // 왼쪽
   leading?: ReactNode;
-  /**
-   * 읽음/안읽음 신호.
-   * - undefined (default): 중립 톤. 리드/언리드 개념 없는 자리(활동 로그·히스토리).
-   * - true: 안 읽음. body/from 강조 + meta primary.
-   * - false: 읽음. 전체 톤 한두 단계 다운.
-   */
-  unread?: boolean;
-
-  // 본문
-  from?: ReactNode;
-  body?: ReactNode;
-  verb?: ReactNode;
-  target?: ReactNode;
-  surface?: ReactNode;
-
-  // 메타
-  meta?: ReactNode;
   trailing?: ReactNode;
-  hoverActions?: ReactNode;
-
-  // 레이아웃·상호작용
-  variant?: ListItemVariant;
-  layout?: ListItemLayout;
-  asChild?: boolean;
+  size?: ListItemSize;
+  align?: ListItemAlign;
+  children?: ReactNode;
 };
 
 type DivProps = Common &
-  Omit<HTMLAttributes<HTMLDivElement>, keyof Common> & {
-    href?: undefined;
-  };
+  Omit<HTMLAttributes<HTMLDivElement>, keyof Common> & { href?: undefined };
 
 type AnchorProps = Common &
-  Omit<AnchorHTMLAttributes<HTMLAnchorElement>, keyof Common> & {
-    href: string;
-  };
+  Omit<AnchorHTMLAttributes<HTMLAnchorElement>, keyof Common> & { href: string };
 
 export type ListItemProps = DivProps | AnchorProps;
 
-/* unread는 명시적으로 넘긴 경우에만 신호. variant는 default를 강제하지 않는다 — 리드/언리드 개념이 없는 자리에서도 자유롭게 쓰기 위함. */
-
-const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem(
+const ListItemRoot = forwardRef<HTMLElement, ListItemProps>(function ListItem(
   props,
   ref,
 ) {
   const {
     leading,
-    unread,
-    from,
-    body,
-    verb,
-    target,
-    surface,
-    meta,
     trailing,
-    hoverActions,
-    variant = "activity",
-    layout = "inline",
-    asChild,
+    size = "md",
+    align = "center",
     className,
+    children,
     ...rest
   } = props as Common & { className?: string } & Record<string, unknown>;
 
-  const isActionMode = verb !== undefined || target !== undefined;
   const isLink = typeof (props as AnchorProps).href === "string";
-  const isInteractive = isLink || typeof (props as HTMLAttributes<HTMLElement>).onClick === "function";
-
-  // read-state class — unread 명시적으로 넘겼을 때만 신호. undefined면 중립.
-  const readStateClass =
-    unread === true ? styles.unread : unread === false ? styles.read : "";
+  const isInteractive =
+    isLink || typeof (props as HTMLAttributes<HTMLElement>).onClick === "function";
 
   const rootClass = [
     styles.root,
-    styles[variant],
-    layout === "stacked" ? styles.stacked : styles.inline,
-    readStateClass,
+    styles[`size-${size}`],
+    styles[`align-${align}`],
     isInteractive ? styles.interactive : "",
     className ?? "",
   ]
     .filter(Boolean)
     .join(" ");
 
-  const leadingNode = leading ? (
-    <span className={styles.leading} aria-hidden>
-      {leading}
-    </span>
-  ) : null;
-
-  // 본문 — 서술 모드 배타. verb/target이 하나라도 있으면 action 모드.
-  // layout=stacked이면 두 줄로 분리: 1줄째 from(+verb+target+surface), 2줄째 body
-  const isStacked = layout === "stacked";
-  const bodyNode = isActionMode ? (
-    isStacked ? (
-      <>
-        <span className={styles.actionBody}>
-          {from && <span className={styles.from}>{from}</span>}
-          {verb && <span className={styles.verb}>{verb}</span>}
-          {target && <span className={styles.target}>{target}</span>}
-          {surface && <span className={styles.surface}>{surface}</span>}
-        </span>
-        {body && <span className={styles.body}>{body}</span>}
-      </>
-    ) : (
-      <span className={styles.actionBody}>
-        {from && <span className={styles.from}>{from}</span>}
-        {verb && <span className={styles.verb}>{verb}</span>}
-        {target && <span className={styles.target}>{target}</span>}
-        {surface && <span className={styles.surface}>{surface}</span>}
-      </span>
-    )
-  ) : isStacked ? (
-    <>
-      {from && <span className={styles.from}>{from}</span>}
-      {body && <span className={styles.body}>{body}</span>}
-    </>
-  ) : (
-    <span className={styles.narrativeBody}>
-      {from && <span className={styles.from}>{from}</span>}
-      {body && <span className={styles.body}>{body}</span>}
-    </span>
-  );
-
-  // trailing: 명시 trailing 우선, 없으면 meta
-  const trailingNode = trailing !== undefined ? (
-    <span className={styles.trailing}>{trailing}</span>
-  ) : meta !== undefined ? (
-    <span className={styles.meta}>{meta}</span>
-  ) : null;
-
-  // hoverActions: 배열이면 간격 유지하며 렌더
-  const hoverNode = hoverActions ? (
-    <span className={styles.hoverActions}>
-      {Children.map(hoverActions, (child) =>
-        isValidElement(child) ? child : child,
-      )}
-    </span>
-  ) : null;
-
   const content = (
     <>
-      {leadingNode}
-      <span className={styles.content}>{bodyNode}</span>
-      {hoverNode}
-      {trailingNode}
+      {leading !== undefined && leading !== null && (
+        <span className={styles.leading} aria-hidden>
+          {leading}
+        </span>
+      )}
+      <span className={styles.content}>{children}</span>
+      {trailing !== undefined && trailing !== null && (
+        <span className={styles.trailing}>{trailing}</span>
+      )}
     </>
   );
 
-  if (asChild) {
-    const only = Children.only(rest.children) as ReactElement<HTMLAttributes<HTMLElement>>;
-    return cloneElement(only, { className: rootClass, ...rest }, content);
-  }
-
   if (isLink) {
-    const { children, ...anchorRest } = rest as AnchorHTMLAttributes<HTMLAnchorElement>;
     return (
       <a
         ref={ref as Ref<HTMLAnchorElement>}
         className={rootClass}
-        {...anchorRest}
+        {...(rest as AnchorHTMLAttributes<HTMLAnchorElement>)}
         href={(props as AnchorProps).href}
       >
         {content}
@@ -203,29 +104,86 @@ const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem(
     );
   }
 
-  const { children, ...divRest } = rest as HTMLAttributes<HTMLDivElement>;
   return (
     <div
       ref={ref as Ref<HTMLDivElement>}
       className={rootClass}
-      data-variant={variant}
-      {...divRest}
+      data-size={size}
+      {...(rest as HTMLAttributes<HTMLDivElement>)}
     >
       {content}
     </div>
   );
 });
 
-ListItem.displayName = "ListItem";
-
-export { ListItem };
+ListItemRoot.displayName = "ListItem";
 
 /* ──────────────────────────────────────────────────────
-   ListItemLeadingIcon — "배경색 + 아이콘" leading 타입.
+   content subcomponents
+   ──────────────────────────────────────────────────── */
+
+type SpanProps = HTMLAttributes<HTMLSpanElement>;
+type DivOnlyProps = HTMLAttributes<HTMLDivElement>;
+
+const Title = forwardRef<HTMLHeadingElement, HTMLAttributes<HTMLHeadingElement>>(
+  function ListItemTitle({ className, children, ...rest }, ref) {
+    return (
+      <div
+        ref={ref as unknown as Ref<HTMLHeadingElement>}
+        className={[styles.title, className ?? ""].filter(Boolean).join(" ")}
+        {...(rest as HTMLAttributes<HTMLDivElement>)}
+      >
+        {children}
+      </div>
+    );
+  },
+);
+Title.displayName = "ListItem.Title";
 
-   Avatar/Icon 사이에 섞어도 정렬이 흔들리지 않도록 같은 사이즈 트랙(xs/sm/md/lg)에 올림.
-   tone 프리셋으로 bg/fg 쌍을 한 번에, 혹은 CSS 변수(--leading-icon-bg / --leading-icon-fg)로
-   세밀 조절. 아이콘 자체는 자식으로 받아 Icon/커스텀 노드 모두 허용.
+const Description = forwardRef<HTMLParagraphElement, HTMLAttributes<HTMLParagraphElement>>(
+  function ListItemDescription({ className, children, ...rest }, ref) {
+    return (
+      <p
+        ref={ref}
+        className={[styles.description, className ?? ""].filter(Boolean).join(" ")}
+        {...rest}
+      >
+        {children}
+      </p>
+    );
+  },
+);
+Description.displayName = "ListItem.Description";
+
+const Meta = forwardRef<HTMLDivElement, DivOnlyProps>(function ListItemMeta(
+  { className, children, ...rest },
+  ref,
+) {
+  return (
+    <div ref={ref} className={[styles.meta, className ?? ""].filter(Boolean).join(" ")} {...rest}>
+      {children}
+    </div>
+  );
+});
+Meta.displayName = "ListItem.Meta";
+
+const MetaDivider = forwardRef<HTMLSpanElement, SpanProps>(function ListItemMetaDivider(
+  { className, ...rest },
+  ref,
+) {
+  return (
+    <span
+      ref={ref}
+      aria-hidden
+      className={[styles.metaDivider, className ?? ""].filter(Boolean).join(" ")}
+      {...rest}
+    />
+  );
+});
+MetaDivider.displayName = "ListItem.MetaDivider";
+
+/* ──────────────────────────────────────────────────────
+   LeadingIcon — "배경색 + 아이콘" leading 타입. 기존 유지.
    ──────────────────────────────────────────────────── */
 
 export type ListItemLeadingIconSize = "xs" | "sm" | "md" | "lg" | "auto";
@@ -244,8 +202,13 @@ export type ListItemLeadingIconProps = Omit<HTMLAttributes<HTMLSpanElement>, "ch
 };
 
 const ListItemLeadingIcon = forwardRef<HTMLSpanElement, ListItemLeadingIconProps>(
-  function ListItemLeadingIcon({ size = "sm", tone = "neutral", className, children, ...rest }, ref) {
-    const cls = [styles.leadingIcon, styles[size], className ?? ""].filter(Boolean).join(" ");
+  function ListItemLeadingIcon(
+    { size = "sm", tone = "neutral", className, children, ...rest },
+    ref,
+  ) {
+    const cls = [styles.leadingIcon, styles[`li-${size}`], className ?? ""]
+      .filter(Boolean)
+      .join(" ");
     return (
       <span ref={ref} aria-hidden {...rest} className={cls} data-tone={tone}>
         {children}
@@ -253,10 +216,23 @@ const ListItemLeadingIcon = forwardRef<HTMLSpanElement, ListItemLeadingIconProps
     );
   },
 );
-
 ListItemLeadingIcon.displayName = "ListItemLeadingIcon";
 
-export { ListItemLeadingIcon };
+/* ──────────────────────────────────────────────────────
+   compound export
+   ──────────────────────────────────────────────────── */
+
+type ListItemCompound = typeof ListItemRoot & {
+  Title: typeof Title;
+  Description: typeof Description;
+  Meta: typeof Meta;
+  MetaDivider: typeof MetaDivider;
+};
+
+const ListItem = ListItemRoot as ListItemCompound;
+ListItem.Title = Title;
+ListItem.Description = Description;
+ListItem.Meta = Meta;
+ListItem.MetaDivider = MetaDivider;
 
-// Slot export (asChild 패턴 지원이 필요한 경우 상위에서 사용)
-export const ListItemSlot = Slot;
+export { ListItem, ListItemLeadingIcon };

package/assets/components/ListItem/index.ts

@@ -1,8 +1,8 @@
 export { ListItem, ListItemLeadingIcon } from "./ListItem";
 export type {
   ListItemProps,
-  ListItemVariant,
-  ListItemLayout,
+  ListItemSize,
+  ListItemAlign,
   ListItemLeadingIconProps,
   ListItemLeadingIconSize,
   ListItemLeadingIconTone,

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/MetricCard/MetricCard.module.css

@@ -1,11 +1,11 @@
 /*
  * MetricCard — 전부 CTDS 토큰 경유.
  * variant:
- *   line  — border만 (조밀한 그리드, 기본)
+ *   line  — border + 은은한 shadow-sm (조밀한 그리드, 기본)
  *   soft  — bg-subtle 표면 (경계 대신 톤)
  *   bare  — border·bg·padding 모두 제거. pure 좌표 전용.
  *           부모 container가 hairline/톤으로 분리를 담당하는 자리에서만 쓴다.
- * 그림자 금지. interactive: href 있을 때만 hover/focus ring.
+ * interactive: href 있을 때만 hover/focus ring.
  */
 
 .root {
@@ -17,20 +17,20 @@
   min-width: 0;
 }
 
-/* line/soft는 자체 chrome(padding+radius+bg/border)을 가진다. */
+/* line/soft는 자체 chrome(padding+radius)을 가진다.
+   line = hairline만, soft = 톤 배경만 — 둘 다 섞지 않는다. */
 .line,
 .soft {
   padding: var(--space-5) var(--space-5);
   border-radius: var(--radius-md);
-  background: var(--bg);
 }
 
 .line {
   border: 1px solid var(--border);
+  box-shadow: var(--shadow-sm);
 }
 
 .soft {
-  border: 1px solid transparent;
   background: var(--bg-subtle);
 }
 

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);