@conscience-technology/ctds 0.3.4 → 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/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/Sidebar/Sidebar.module.css

@@ -73,9 +73,9 @@
      Body 안쪽 콘텐츠 래퍼(nav/섹션 리스트 등)에 깐다. */
   /* padding-top·padding-bottom도 두지 않음 — Header 아래 숨돌림, Footer 위
      마지막 항목 숨돌림 모두 소비처가 안쪽 래퍼의 padding-block으로 공급. */
-  /* mask-image 금지 — Body 안에 "고정 상단 블록(railTop 등 primary CTA + 검색)"을
-     꽂는 소비처가 많아서 fade가 걸리면 그 블록 상단이 흐려져 "밝은 입체 바"
-     착시를 만듦(특히 primary solid 버튼에서 심함). */
+  /* mask-image 기본 off. 켜고 싶으면 Sidebar.Body의 `fade` prop 사용.
+     top fade는 Body 안에 "고정 상단 블록(primary CTA + 검색)"을 꽂는 소비처에선
+     그 블록 상단이 흐려져 "밝은 입체 바" 착시를 만들므로 주의. */
 }
 
 /* Body 자식이 flex column에서 수축돼 header가 뭉개지는 걸 방지.
@@ -84,15 +84,92 @@
   flex: 0 0 auto;
 }
 
+/* fade mask opt-in — Body에 `fade="top|bottom|both"` prop을 주면 켜짐.
+   페이드 크기는 `--sidebar-body-fade-size` 토큰(기본 --space-3). 소비처가 늘릴 수 있음.
+   주의: top fade는 Body 안에 고정 상단 블록(primary CTA 등)이 없을 때만 안전.
+   있으면 그 블록 상단이 깎여 "흰 입체 바" 착시가 생김. */
+.body[data-fade] {
+  --sidebar-body-fade-size: var(--space-3);
+}
+
+/* mask-image의 #000은 색이 아니라 "완전 불투명" alpha marker — lint-hardcoded ignore. */
+.body[data-fade="top"] {
+  mask-image: linear-gradient(
+    to bottom,
+    transparent 0,
+    #000 var(--sidebar-body-fade-size), /* lint-hardcoded: ignore */
+    #000 100% /* lint-hardcoded: ignore */
+  );
+  -webkit-mask-image: linear-gradient(
+    to bottom,
+    transparent 0,
+    #000 var(--sidebar-body-fade-size), /* lint-hardcoded: ignore */
+    #000 100% /* lint-hardcoded: ignore */
+  );
+}
+
+.body[data-fade="bottom"] {
+  mask-image: linear-gradient(
+    to bottom,
+    #000 0, /* lint-hardcoded: ignore */
+    #000 calc(100% - var(--sidebar-body-fade-size)), /* lint-hardcoded: ignore */
+    transparent 100%
+  );
+  -webkit-mask-image: linear-gradient(
+    to bottom,
+    #000 0, /* lint-hardcoded: ignore */
+    #000 calc(100% - var(--sidebar-body-fade-size)), /* lint-hardcoded: ignore */
+    transparent 100%
+  );
+}
+
+.body[data-fade="both"] {
+  mask-image: linear-gradient(
+    to bottom,
+    transparent 0,
+    #000 var(--sidebar-body-fade-size), /* lint-hardcoded: ignore */
+    #000 calc(100% - var(--sidebar-body-fade-size)), /* lint-hardcoded: ignore */
+    transparent 100%
+  );
+  -webkit-mask-image: linear-gradient(
+    to bottom,
+    transparent 0,
+    #000 var(--sidebar-body-fade-size), /* lint-hardcoded: ignore */
+    #000 calc(100% - var(--sidebar-body-fade-size)), /* lint-hardcoded: ignore */
+    transparent 100%
+  );
+}
+
 /* Brand preset ─────────────────────────────────────────
    Header 안에 꽂히는 preset. symbol은 항상, wordmark는 expanded일 때만 렌더.
    상한선 토큰으로 max-height 강제 — 사용처가 그 안에서 자유롭게 크기 지정.
-   좌우/상하 padding은 소비처가 공급. */
+   Header 자체 좌우/상하 padding은 소비처가 공급(래퍼 축).
+   Brand 안쪽 좌우 padding은 벤더가 공급 — MenuItem이 자체 padding-inline을
+   가지므로 Brand symbol이 아래 MenuItem 아이콘과 같은 X축에 서려면
+   Brand도 동일한 inner padding을 가져야 함(아니면 symbol이 라벨 영역과 anti-flush).
+   width: 100% + collapsed 중앙 정렬: Brand가 Header 폭을 전부 받아야 collapsed일 때
+   justify-content: center가 "Header 가로 중앙"으로 유효해짐. */
 .brand {
   display: flex;
   align-items: center;
   gap: var(--space-2);
   min-height: var(--control-h-md);
+  /* MenuItem이 자체 padding-inline(space-2)을 가지므로 Brand symbol이 아래
+     라벨들의 아이콘과 같은 X축에 서려면 Brand도 동일한 inner padding을 가져야 함.
+     Header 안에 Brand + 다른 자식이 공존하는 소비처가 있으므로 width는 건드리지
+     않고 inner padding만 공급. */
+  padding-inline: var(--space-2);
+  box-sizing: border-box;
+}
+
+/* collapsed일 땐 wordmark가 사라져 symbol 하나만 남으므로 Header 폭을 전부 받아
+   가로 중앙 정렬. 안 그러면 Brand가 symbol 폭에만 머물러 Header 좌측에 붙음.
+   inner padding도 제거 — collapsed Header는 자체적으로 좁고 symbol 1개만 있어
+   추가 안쪽 여백이 필요 없음. */
+.root[data-collapsed] .brand {
+  width: 100%;
+  justify-content: center;
+  padding-inline: 0;
 }
 
 .brandSymbol {

package/assets/components/Sidebar/Sidebar.tsx

@@ -75,8 +75,16 @@ function SidebarHeader({ children, className, ...rest }: HTMLAttributes<HTMLDivE
    Header와 Footer 사이의 세로 스크롤 영역.
    여러 개를 두면 각각 독립적인 스크롤 트랙이 됨.
    ResizeObserver로 scrollHeight > clientHeight 감지 → Footer가 자동으로
-   상단 hairline을 켬. 메뉴가 적으면 선 없음, 많으면 자연스럽게 분리선 등장. */
-function SidebarBody({ children, className, ...rest }: HTMLAttributes<HTMLDivElement>) {
+   상단 hairline을 켬. 메뉴가 적으면 선 없음, 많으면 자연스럽게 분리선 등장.
+
+   fade: 스크롤 트랙 상/하단 소프트 fade mask. "top" | "bottom" | "both" | "none".
+   기본 "none" — 켤 때만 켠다(소비처가 Body 안에 고정 상단 블록을 두면 top fade가
+   그 블록을 깎아 "흰 입체 바" 착시를 만드므로 opt-in). */
+export interface SidebarBodyProps extends HTMLAttributes<HTMLDivElement> {
+  fade?: "top" | "bottom" | "both" | "none";
+}
+
+function SidebarBody({ children, className, fade = "none", ...rest }: SidebarBodyProps) {
   const ref = useRef<HTMLDivElement>(null);
   const { setBodyOverflow } = useSidebar();
 
@@ -100,6 +108,7 @@ function SidebarBody({ children, className, ...rest }: HTMLAttributes<HTMLDivEle
     <div
       ref={ref}
       data-sidebar-slot="body"
+      data-fade={fade !== "none" ? fade : undefined}
       className={[styles.body, className ?? ""].filter(Boolean).join(" ")}
       {...rest}
     >

package/assets/components/SplitButton/SplitButton.module.css

@@ -94,9 +94,9 @@
 .sm .menu { padding-inline: var(--space-1_5); }
 
 .md { --split-h: var(--control-h-md); --btn-icon-size: var(--space-4); }
-.md .part { font-size: var(--text-sm); gap: var(--space-1); }
-.md .main { padding-inline: var(--space-2); }
-.md .menu { padding-inline: var(--space-1_5); }
+.md .part { font-size: var(--text-sm); gap: var(--space-1_5); }
+.md .main { padding-inline: var(--space-3); }
+.md .menu { padding-inline: var(--space-2); }
 
 .lg { --split-h: var(--control-h-lg); --btn-icon-size: var(--space-4); }
 .lg .part { font-size: var(--text-sm); gap: var(--space-1_5); }