sellmate-design-system-react 0.4.0 → 0.6.0

package/dist/components/SGnb/SGnb.d.ts

@@ -3,21 +3,32 @@ import { type SGnbType, type SGnbHeader, type SGnbColor, type SGnbMenuItem } fro
 export interface SGnbProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color'> {
     /** 메뉴 스타일: box(라운드) / belt(풀폭 행). 미지정 시 SLayout 의 type 을 따른다. */
     type?: SGnbType;
-    /** 상단바 구조: fix(GNB 폭 고정) / full(레이아웃 전폭). 미지정 시 SLayout 의 header 를 따른다. */
+    /**
+     * 상단바 구조: fix(GNB 폭 고정) / full(레이아웃 전폭). 미지정 시 SLayout 의 header 를 따른다.
+     * 단, useRail 이고 레일에 children 없는 아이템이 있으면 메뉴 폭이 출렁이므로 full 로 강제된다.
+     */
     header?: SGnbHeader;
     /** 색상 테마: light / dark */
     color?: SGnbColor;
-    /** 메뉴 트리 (depth1 → depth2 → depth3) */
+    /** 메뉴 트리 (depth1 → depth2 → depth3). useRail 이면 첫 depth 가 레일이 되고 그 children 이 depth1 이 된다. */
     items: SGnbMenuItem[];
+    /**
+     * 좌측 레일 사용 여부. 켜면 items 의 첫 depth 가 아이콘+라벨 버튼의 세로 레일로 서고,
+     * 선택된 레일 아이템의 children 이 오른쪽 메뉴 패널에 깔린다. 미지정 시 SLayout 의 useRail 을 따른다.
+     * children 없는 레일 아이템이 활성이면 메뉴 패널은 렌더되지 않고 레일만 남는다.
+     */
+    useRail?: boolean;
     /** 현재 선택된 아이템 value */
     value?: string;
     /** 선택 변경 (sdUpdate) */
     onValueChange?: (value: string) => void;
+    /** 레일 선택 변경. 레일 아이템을 눌러 패널이 바뀔 때 알린다(선택 상태는 SGnb 가 자체 관리). */
+    onRailChange?: (value: string) => void;
     /** 접힘(레일) 상태. 미지정 시 SLayout 의 folded 를 따른다. */
     folded?: boolean;
     /** 접힘 토글 (sdFoldChange) */
     onFoldChange?: (folded: boolean) => void;
-    /** 앱런처(그리드) 버튼 클릭. 미지정 시 런처 버튼을 렌더하지 않는다. */
+    /** 앱런처(그리드) 버튼 클릭. 미지정 시 런처 버튼을 렌더하지 않는다. 접힘 레일(fix)에는 폴드 버튼만 남으므로 표시되지 않는다. */
     onLauncherClick?: () => void;
     /** 상단바 로고 영역 (slot) */
     logo?: ReactNode;
@@ -27,12 +38,20 @@ export interface SGnbProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color'>
 /**
  * SGnb — 글로벌 네비게이션.
  * 세 축이 독립이다: type(box/belt) = 메뉴 스타일, header(fix/full) = 상단바 구조,
- * color(light/dark) = 색. 치수는 --cmp-gnbBox / --cmp-gnbBelt, 색은 --cmp-light / --cmp-dark 토큰 합성.
+ * color(light/dark) = 색. 치수는 --cmp-gnb / --cmp-gnb-box / --cmp-gnb-belt, 색은 --cmp-gnb-light / --cmp-gnb-dark 토큰 합성.
  *
  * header 가 배치와 접힘 형태를 정한다:
- * - fix: 상단바가 GNB 컬럼(메뉴 폭) 안에 있다. 접으면 48px 세로 레일로 좁혀진다.
+ * - fix: 상단바가 GNB 컬럼(메뉴 폭) 안에 있다. 접으면 48px 세로 레일로 좁혀지고 상단바에는 폴드 버튼만 남는다.
  * - full: 상단바가 레이아웃 전폭을 가로지르고 그 아래 [메뉴 | 페이지]. 접으면 메뉴만 사라진다.
  *
+ * useRail 이면 items 의 첫 depth 가 좌측 레일(아이콘+라벨 68px)로 서고, 선택된 레일 아이템의
+ * children 이 메뉴 패널의 depth1 이 된다 — 트리는 그대로 두고 어디부터 그릴지만 바뀐다.
+ * children 없는 레일 아이템은 자기 자신이 선택(리프)이라 메뉴 패널을 렌더하지 않는다. 이런 리프가
+ * 하나라도 있으면 활성에 따라 메뉴 폭이 출렁이므로 header 는 full 로 강제해 상단바를 전폭에 고정한다.
+ *
+ * 접힘/펼침은 GNB_FOLD_MS 동안의 슬라이드다 — 레일·메뉴가 함께 왼쪽으로 빠져나가고 펼치면 오른쪽에서 들어온다.
+ * 페이지 쪽 폭은 fix 면 이 컴포넌트의 폭 전환이, full 이면 SLayout 의 메뉴 열 전환이 같은 길이로 맞춘다.
+ *
  * SLayout 안에서 쓰면 type·header·folded 를 context 에서 읽어 앱이 중복으로 넘길 필요가 없다.
  * SLayout 없이 단독으로도 동작한다(prop 또는 기본값 사용).
  */