sellmate-design-system-react 0.3.0 → 0.5.0

package/README.md

@@ -21,8 +21,8 @@ npm install sellmate-design-system-react
 
 ```css
 /* app globals.css */
-@import "tailwindcss";
-@import "sellmate-design-system-react/theme.css";
+@import 'tailwindcss';
+@import 'sellmate-design-system-react/theme.css';
 @source "../node_modules/sellmate-design-system-react/dist";
 ```
 
@@ -34,37 +34,100 @@ npm install sellmate-design-system-react
 Tailwind를 쓰지 않는 앱은 컴파일된 CSS를 직접 import 합니다.
 
 ```ts
-import "sellmate-design-system-react/styles.css";
+import 'sellmate-design-system-react/styles.css';
+```
+
+## Next.js (App Router)
+
+별도 설정 없이 동작합니다. `dist` 가 이미 빌드되어 있으므로 `transpilePackages` 는 필요 없습니다.
+
+전역 CSS 는 위 **방식 1** 과 같습니다. `@source` 는 **CSS 파일 기준 상대경로**이므로 `app/globals.css` 에 둔다면 다음과 같습니다.
+
+```css
+/* app/globals.css */
+@import 'tailwindcss';
+@import 'sellmate-design-system-react/theme.css';
+@source "../node_modules/sellmate-design-system-react/dist";
+```
+
+### 서버 컴포넌트에서 그대로 import 할 수 있습니다
+
+패키지 엔트리가 `"use client"` 로 선언된 클라이언트 경계라, 서버 컴포넌트에서 바로 import 해도 됩니다. 서버에서 렌더(SSR)된 뒤 클라이언트에서 하이드레이션됩니다.
+
+```tsx
+// app/page.tsx — "use client" 없음
+import { SButton } from 'sellmate-design-system-react';
+
+export default function Page() {
+  return <SButton color="primary" size="md" label="확인" />;
+}
+```
+
+### 이벤트 핸들러가 필요하면 소비자 쪽에 `"use client"`
+
+RSC 경계를 넘어 **함수는 전달할 수 없습니다.** 위 페이지에 `onClick` 을 추가하면 빌드가 실패합니다.
+
+```text
+Error: Event handlers cannot be passed to Client Component props.
+```
+
+이는 라이브러리 제약이 아니라 React 서버 컴포넌트의 규칙입니다. 핸들러·상태가 필요한 화면은 그 파일을 클라이언트 컴포넌트로 만드세요.
+
+```tsx
+'use client';
+
+import { useState } from 'react';
+import { SCheckbox } from 'sellmate-design-system-react';
+
+export function AgreeField() {
+  const [value, setValue] = useState(false);
+  return <SCheckbox value={value} onValueChange={setValue} label="동의" />;
+}
+```
+
+동작을 직접 확인하려면 Next playground 를 띄우세요 — 이 패키지를 소비 앱과 동일하게 `dist` 로 소비합니다.
+
+```bash
+npm run playground:next   # http://localhost:3010
 ```
 
 ## 사용법
 
 ```tsx
-import { Button } from "sellmate-design-system-react";
+import { SButton } from 'sellmate-design-system-react';
 
 export function Example() {
-  return (
-    <Button variant="primary" size="md" onClick={() => alert("clicked")}>
-      확인
-    </Button>
-  );
+  return <SButton color="primary" size="md" label="확인" onClick={() => alert('clicked')} />;
 }
 ```
 
+모든 컴포넌트는 **`S` 접두어**를 씁니다(`SButton`, `SInput` …). 공개 타입도 마찬가지입니다(`SButtonProps`).
+
+`SButton` 은 텍스트를 **`label`(문자열)로만** 받습니다 — `children` 은 받지 않으며, 아이콘은 `icon`/`rightIcon` 을 씁니다. 색상 prop 은 `color` 입니다(`variant` 아님).
+
 ## 제공 컴포넌트
 
-| 분류 | 컴포넌트 |
-| --- | --- |
-| 버튼·액션 | `Button` · `GhostButton` · `DropdownButton` · `TextLink` · `Toggle` · `Switch` |
-| 폼 입력 | `Input` · `Textarea` · `NumberInput` · `BarcodeInput` · `Select` · `Checkbox` · `Radio` · `RadioButton` · `Chip` · `ChipInput` · `Field` · `FilePicker` |
-| 날짜 | `Calendar` · `DatePicker` · `DateRangePicker` |
-| 표시·피드백 | `Badge` · `Tag` · `Card` · `Callout` · `Divider` · `Tooltip` · `Popover` · `Popup` · `Guide` · `Toast` |
-| 진행 상태 | `LinearProgress` · `CircleProgress` · `LoadingContainer` · `LoadingModal` |
-| 모달 | `ModalContainer` · `ConfirmModal` · `ActionModal` |
-| 데이터 표시 | `Table` · `KeyValueTable` · `Tabs` · `Pagination` |
-| 아이콘 | `Icon` |
-
-유틸리티로 클래스 병합 헬퍼 `cn`도 export 합니다.
+분류는 `src/index.ts` 의 export 그룹과 동일합니다.
+
+| 분류        | 컴포넌트                                                                                                                                                                                                                         |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Atoms       | `SIcon` · `SBadge` · `SCard` · `SDivider` · `STag` · `SButton` · `SCallout` · `SLinearProgress` · `SCircleProgress` · `SLoadingContainer`                                                                                        |
+| Control     | `STextLink` · `SDropdownButton` · `SGhostButton` · `SSwitch` · `SToggle`                                                                                                                                                         |
+| Overlays    | `STooltip` · `SPopover` · `SPortal` · `SPopup` · `SGuide`                                                                                                                                                                        |
+| Modals      | `SConfirmModal` · `SActionModal` · `SLoadingModal`                                                                                                                                                                               |
+| Layout      | `SGnb` · `SLayout` · `SPage`                                                                                                                                                                                                     |
+| Navigation  | `STabs` · `SPagination`                                                                                                                                                                                                          |
+| Data        | `STable` · `SKeyValueTable`                                                                                                                                                                                                      |
+| Feedback    | `SToast`                                                                                                                                                                                                                         |
+| SField (폼) | `SForm` · `SField` · `SCheckbox` · `SRadio` · `SRadioButton` · `SInput` · `STextarea` · `SSelect` · `SNumberInput` · `SChip` · `SChipInput` · `SBarcodeInput` · `SCalendar` · `SDatePicker` · `SDateRangePicker` · `SFilePicker` |
+
+`SModalContainer` 는 모달 3종의 내부 공통 컨테이너로 **공개 export 가 아닙니다.** 소비자는 `SConfirmModal`/`SActionModal`/`SLoadingModal` 을 사용하세요.
+
+유틸리티도 함께 export 합니다.
+
+- `cn` — 클래스 병합 헬퍼
+- `resolveColor` · `isColorKey` · `COLOR_KEYS` · `SColor` · `SColorKey` — 색상 토큰 유틸
+- `Rule` — `rules` prop(`SField` · `SChip` · `SBarcodeInput` 등)에 넘기는 검증 함수 타입
 
 ## 특징
 

package/dist/components/SGnb/SGnb.cjs

@@ -3095,73 +3095,70 @@ function SGhostButton({
 }
 
 // src/components/SGnb/gnb.config.ts
-var belt = (p) => `var(--cmp-gnbBelt-${p})`;
-var box = (p) => `var(--cmp-gnbBox-${p})`;
-var light = (p) => `var(--cmp-light-${p})`;
-var dark = (p) => `var(--cmp-dark-${p})`;
+var gnb = (p) => `var(--cmp-gnb-${p})`;
+var box = (p) => `var(--cmp-gnb-box-${p})`;
+var belt = (p) => `var(--cmp-gnb-belt-${p})`;
+var light = (p) => `var(--cmp-gnb-light-${p})`;
+var dark = (p) => `var(--cmp-gnb-dark-${p})`;
+var HEADER_TOP = {
+  topHeight: gnb("top-height"),
+  topPaddingX: gnb("top-paddingX"),
+  topGap: gnb("top-gap"),
+  logoHeight: gnb("logo-height")
+};
 var GNB_HEADER = {
-  fix: {
-    topHeight: belt("top-height"),
-    topPaddingX: belt("top-paddingX"),
-    topGap: belt("top-gap"),
-    logoHeight: belt("logo-height")
-  },
-  full: {
-    topHeight: box("top-height"),
-    topPaddingX: box("paddingX"),
-    topGap: box("gap"),
-    // 상단바 gap (버튼 간 세부 gap 은 --cmp-gnbBox-button-gap)
-    logoHeight: box("logo-height")
-  }
+  fix: HEADER_TOP,
+  full: HEADER_TOP
 };
 var GNB_MENU = {
   box: {
-    // menu.body.padding 은 전방향 토큰 → 세로 패딩과 아이템 좌우 여백 양쪽에 쓴다
-    bodyPaddingY: box("menu-body-padding"),
-    itemMarginX: box("menu-body-padding"),
-    itemPaddingY: box("item-paddingY"),
+    // 바디 패딩·세로 패딩·chevron 은 gnb 로 통합된 공통 토큰
+    bodyPaddingY: gnb("body-padding"),
+    itemMarginX: gnb("body-padding"),
+    // 전방향 토큰 → 아이템 좌우 여백에도 사용
+    itemPaddingY: gnb("item-paddingY"),
     itemPaddingRight: box("item-paddingRight"),
     itemGap: box("item-gap"),
     itemRadius: box("item-radius"),
-    itemArrow: box("item-arrow"),
+    itemArrow: gnb("item-chevron-size"),
     depth1PaddingLeft: box("item-depth1-paddingLeft"),
     depth2PaddingLeft: box("item-depth2-paddingLeft"),
     depth3PaddingLeft: box("item-depth3-paddingLeft"),
     depth1Icon: box("item-depth1-icon"),
     depth1FontSize: 14,
-    // token: gnbBox.item.typography.bold.fontSize
+    // token: gnb.box.item.typography.selected.fontSize
     depth1LineHeight: 24,
-    // token: gnbBox.item.typography.bold.lineHeight
+    // token: gnb.box.item.typography.selected.lineHeight
     depth1FontWeight: 700,
     itemFontSize: 14,
-    // token: gnbBox.item.typography.default.fontSize
+    // token: gnb.box.item.typography.default.fontSize
     itemLineHeight: 24
-    // token: gnbBox.item.typography.default.lineHeight
+    // token: gnb.box.item.typography.default.lineHeight
   },
   belt: {
-    bodyPaddingY: belt("body-paddingY"),
+    bodyPaddingY: gnb("body-padding"),
     itemMarginX: "0px",
     // belt 토큰에 가로 여백 없음 → 풀폭 행 (들여쓰기는 depth*-paddingLeft 전담)
-    itemPaddingY: belt("item-paddingY"),
+    itemPaddingY: gnb("item-paddingY"),
     itemPaddingRight: belt("item-paddingRight"),
     itemGap: belt("item-gap"),
     itemRadius: "0px",
     // belt 토큰에 radius 없음 → 풀폭 행
-    itemArrow: belt("item-icon"),
+    itemArrow: gnb("item-chevron-size"),
     depth1PaddingLeft: belt("item-depth1-paddingLeft"),
     depth2PaddingLeft: belt("item-depth2-paddingLeft"),
     depth3PaddingLeft: belt("item-depth3-paddingLeft"),
-    depth1Icon: box("item-depth1-icon"),
-    // belt 토큰에 depth1-icon 없음 → box 값(20) 공유
+    depth1Icon: belt("item-depth1-icon"),
+    // belt 전용 depth1 아이콘 토큰(16)
     depth1FontSize: 13,
-    // token: gnbBelt.item.depth1.typography.fontSize
+    // token: gnb.belt.item.depth1.typography.fontSize
     depth1LineHeight: 22,
-    // token: gnbBelt.item.depth1.typography.lineHeight
+    // token: gnb.belt.item.depth1.typography.lineHeight
     depth1FontWeight: 700,
     itemFontSize: 12,
-    // token: gnbBelt.item.typography.default.fontSize
+    // token: gnb.belt.item.typography.default.fontSize
     itemLineHeight: 20
-    // token: gnbBelt.item.typography.default.lineHeight
+    // token: gnb.belt.item.typography.default.lineHeight
   }
 };
 var GNB_COLORS = {
@@ -3174,7 +3171,9 @@ var GNB_COLORS = {
     itemColorDefault: light("item-fg-default"),
     itemColorHover: light("item-fg-hover"),
     itemColorActive: light("item-fg-selected"),
-    itemChevron: light("item-chevron")
+    itemChevron: light("item-chevron"),
+    itemIcon: "grey_65",
+    railFgDefault: light("rail-fg-default")
   },
   dark: {
     panelBg: dark("bg"),
@@ -3185,19 +3184,41 @@ var GNB_COLORS = {
     itemColorDefault: dark("item-fg-default"),
     itemColorHover: dark("item-fg-hover"),
     itemColorActive: dark("item-fg-selected"),
-    itemChevron: dark("item-chevron")
+    itemChevron: dark("item-chevron"),
+    itemIcon: "grey_55",
+    railFgDefault: dark("rail-fg-default")
   }
 };
 var GNB_COMMON = {
   /** 접힘 레일 폭. header="full" 은 접으면 메뉴만 사라져 레일이 없으므로 fix 전용. */
-  foldWidth: belt("fold-width"),
-  /**
-   * 상단바 아이콘 버튼 사이 간격. fix 레일(세로 스택)의 gap·상하 여백에 쓴다.
-   * 레일 전용 여백 토큰이 따로 없어 같은 값(8px)인 이 토큰으로 재해석했다.
-   */
-  buttonGap: box("button-gap")
-};
+  foldWidth: gnb("fold-width")
+};
+var GNB_RAIL = {
+  padding: gnb("rail-padding"),
+  gap: gnb("rail-gap"),
+  itemWidth: gnb("rail-item-width"),
+  itemPaddingTop: gnb("rail-item-paddingTop"),
+  itemPaddingBottom: gnb("rail-item-paddingBottom"),
+  itemRadius: gnb("rail-item-radius"),
+  itemIcon: gnb("rail-item-icon"),
+  // 타이포 (theme.css 에 gnb 타이포 변수 없음 → 토큰 값 직접 명시)
+  itemFontSize: 11,
+  // token: gnb.rail.item.typography.default.fontSize
+  itemLineHeight: 18,
+  // token: gnb.rail.item.typography.default.lineHeight
+  itemFontWeight: 500,
+  // token: gnb.rail.item.typography.default.fontWeight
+  itemFontWeightSelected: 700
+  // token: gnb.rail.item.typography.selected.fontWeight
+};
+var GNB_RAIL_WIDTH = 68;
+var GNB_FOLD_MS = 200;
+var GNB_EXPAND_MS = 200;
 var GNB_MENU_WIDTH = 240;
+function findGnbRailValue(items, value) {
+  if (items.some((item) => item.value === value)) return value;
+  return findGnbAncestors(items, value)[0];
+}
 function findGnbAncestors(items, value) {
   const walk = (list, trail) => {
     for (const item of list) {
@@ -3215,6 +3236,7 @@ var SLayoutContext = react.createContext(null);
 react.forwardRef(function SLayout2({
   type = "box",
   header = "fix",
+  useRail = false,
   folded,
   defaultFolded = false,
   onFoldedChange,
@@ -3234,13 +3256,17 @@ react.forwardRef(function SLayout2({
     [isControlled, onFoldedChange]
   );
   const ctx = react.useMemo(
-    () => ({ type, header, folded: currentFolded, setFolded }),
-    [type, header, currentFolded, setFolded]
+    () => ({ type, header, useRail, folded: currentFolded, setFolded }),
+    [type, header, useRail, currentFolded, setFolded]
   );
   const isFullHeader = header === "full";
+  const gnbColumnWidth = useRail ? GNB_RAIL_WIDTH + GNB_MENU_WIDTH : GNB_MENU_WIDTH;
   const frameStyle = isFullHeader ? {
-    gridTemplateColumns: `${currentFolded ? 0 : GNB_MENU_WIDTH}px 1fr`,
-    gridTemplateRows: `${GNB_HEADER[header].topHeight} 1fr`
+    gridTemplateColumns: `${currentFolded ? 0 : gnbColumnWidth}px 1fr`,
+    gridTemplateRows: `${GNB_HEADER[header].topHeight} 1fr`,
+    // 메뉴가 미끄러지는 동안 페이지 열도 같은 길이로 따라와야 한 덩어리로 읽힌다.
+    // (fix 는 SGnb 가 제 폭을 직접 전환하므로 프레임이 손댈 게 없다)
+    transition: `grid-template-columns ${GNB_FOLD_MS}ms ease-out`
   } : void 0;
   return /* @__PURE__ */ jsxRuntime.jsx(SLayoutContext.Provider, { value: ctx, children: /* @__PURE__ */ jsxRuntime.jsx(
     "div",
@@ -3265,8 +3291,10 @@ var SGnb = react.forwardRef(function SGnb2({
   header: headerProp,
   color = "light",
   items,
+  useRail: useRailProp,
   value = "",
   onValueChange,
+  onRailChange,
   folded: foldedProp,
   onFoldChange,
   onLauncherClick,
@@ -3280,6 +3308,7 @@ var SGnb = react.forwardRef(function SGnb2({
   const type = typeProp ?? layout?.type ?? "box";
   const header = headerProp ?? layout?.header ?? "fix";
   const folded = foldedProp ?? layout?.folded ?? false;
+  const useRail = useRailProp ?? layout?.useRail ?? false;
   const H = GNB_HEADER[header];
   const M = GNB_MENU[type];
   const C = GNB_COLORS[color];
@@ -3287,6 +3316,9 @@ var SGnb = react.forwardRef(function SGnb2({
     () => new Set(findGnbAncestors(items, value))
   );
   const [hoveredKey, setHoveredKey] = react.useState(null);
+  const [activeRail, setActiveRail] = react.useState(
+    () => findGnbRailValue(items, value) ?? items[0]?.value
+  );
   react.useEffect(() => {
     const ancestors = findGnbAncestors(items, value);
     if (ancestors.length === 0) return;
@@ -3297,6 +3329,15 @@ var SGnb = react.forwardRef(function SGnb2({
       return next;
     });
   }, [items, value]);
+  react.useEffect(() => {
+    const owner = findGnbRailValue(items, value);
+    if (owner !== void 0) setActiveRail(owner);
+  }, [items, value]);
+  react.useEffect(() => {
+    setActiveRail(
+      (prev) => prev !== void 0 && items.some((item) => item.value === prev) ? prev : items[0]?.value
+    );
+  }, [items]);
   const toggleExpand = (key) => {
     setExpandedKeys((prev) => {
       const next = new Set(prev);
@@ -3313,16 +3354,58 @@ var SGnb = react.forwardRef(function SGnb2({
     }
     onValueChange?.(item.value);
   };
+  const handleRailClick = (item) => {
+    if (item.disabled) return;
+    setActiveRail(item.value);
+    onRailChange?.(item.value);
+    if (!item.children || item.children.length === 0) onValueChange?.(item.value);
+  };
   const handleFoldToggle = () => {
     const next = !folded;
     onFoldChange?.(next);
     if (foldedProp === void 0) layout?.setFolded(next);
   };
-  const renderItem = (item, depth) => {
+  const renderRailItem = (item) => {
+    const isActive = item.value === activeRail;
+    const isHovered = hoveredKey === item.value && !item.disabled;
+    return /* @__PURE__ */ jsxRuntime.jsx("li", { children: /* @__PURE__ */ jsxRuntime.jsxs(
+      "button",
+      {
+        type: "button",
+        disabled: item.disabled,
+        "aria-current": isActive ? "true" : void 0,
+        className: "box-border flex select-none flex-col items-center border-none bg-transparent transition-colors duration-150",
+        style: {
+          width: GNB_RAIL.itemWidth,
+          paddingTop: GNB_RAIL.itemPaddingTop,
+          paddingBottom: GNB_RAIL.itemPaddingBottom,
+          borderRadius: GNB_RAIL.itemRadius,
+          backgroundColor: isActive ? C.itemBgSelected : isHovered ? C.itemBgHover : C.itemBgDefault,
+          color: isActive ? C.itemColorActive : C.railFgDefault,
+          // <button> 의 UA 폰트를 끊고 앱 폰트를 잇는다 (메뉴 아이템과 같은 이유)
+          fontFamily: "inherit",
+          fontSize: GNB_RAIL.itemFontSize,
+          lineHeight: `${GNB_RAIL.itemLineHeight}px`,
+          fontWeight: isActive ? GNB_RAIL.itemFontWeightSelected : GNB_RAIL.itemFontWeight,
+          opacity: item.disabled ? 0.4 : 1,
+          cursor: item.disabled ? "not-allowed" : "pointer"
+        },
+        onClick: () => handleRailClick(item),
+        onMouseEnter: () => setHoveredKey(item.value),
+        onMouseLeave: () => setHoveredKey((prev) => prev === item.value ? null : prev),
+        children: [
+          item.icon && /* @__PURE__ */ jsxRuntime.jsx(SIcon, { name: item.icon, size: GNB_RAIL.itemIcon, className: "shrink-0" }),
+          /* @__PURE__ */ jsxRuntime.jsx("span", { className: "w-full overflow-hidden text-ellipsis whitespace-nowrap text-center", children: item.label })
+        ]
+      }
+    ) }, item.value);
+  };
+  const renderItem = (item, depth, branchHasIcon = false) => {
     const hasChildren = !!(item.children && item.children.length > 0);
     const isSelected = !hasChildren && item.value === value;
     const isExpanded = expandedKeys.has(item.value);
     const isHovered = hoveredKey === item.value && !item.disabled;
+    const iconBranch = depth === 1 ? !!item.icon : branchHasIcon;
     const itemStyle = {
       gap: M.itemGap,
       paddingTop: M.itemPaddingY,
@@ -3359,8 +3442,11 @@ var SGnb = react.forwardRef(function SGnb2({
             onMouseEnter: () => setHoveredKey(item.value),
             onMouseLeave: () => setHoveredKey((prev) => prev === item.value ? null : prev),
             children: [
-              depth === 1 && item.icon && /* @__PURE__ */ jsxRuntime.jsx(SIcon, { name: item.icon, size: M.depth1Icon, className: "shrink-0" }),
-              /* @__PURE__ */ jsxRuntime.jsx("span", { className: "min-w-0 flex-1 overflow-hidden text-ellipsis whitespace-nowrap", children: item.label }),
+              depth === 1 && item.icon && /* @__PURE__ */ jsxRuntime.jsx(SIcon, { name: item.icon, size: M.depth1Icon, color: C.itemIcon, className: "shrink-0" }),
+              /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "min-w-0 flex-1 overflow-hidden text-ellipsis whitespace-nowrap flex flex-no-wrap items-center", children: [
+                depth > 1 && iconBranch ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: "w-[20px] h-[24px] flex items-center justify-center mr-[8px]", children: "-" }) : null,
+                item.label
+              ] }),
               item.tag !== void 0 && item.tag !== "" && /* @__PURE__ */ jsxRuntime.jsx(
                 STag,
                 {
@@ -3378,28 +3464,53 @@ var SGnb = react.forwardRef(function SGnb2({
                   size: M.itemArrow,
                   color: C.itemChevron,
                   rotate: isExpanded ? 180 : 0,
-                  className: "shrink-0 transition-transform duration-150"
+                  className: "shrink-0 transition-transform duration-200"
                 }
               )
             ]
           }
         ),
-        hasChildren && isExpanded && /* @__PURE__ */ jsxRuntime.jsx("ul", { className: "m-0 flex list-none flex-col p-0", children: item.children.map((child) => renderItem(child, depth + 1)) })
+        hasChildren && /* @__PURE__ */ jsxRuntime.jsx(
+          "div",
+          {
+            className: "grid",
+            style: {
+              gridTemplateRows: isExpanded ? "1fr" : "0fr",
+              transition: `grid-template-rows ${GNB_EXPAND_MS}ms ease-out`
+            },
+            children: /* @__PURE__ */ jsxRuntime.jsx(
+              "ul",
+              {
+                className: "m-0 flex min-h-0 list-none flex-col overflow-hidden p-0",
+                style: {
+                  visibility: isExpanded ? "visible" : "hidden",
+                  transition: `visibility 0s linear ${isExpanded ? "0s" : `${GNB_EXPAND_MS}ms`}`
+                },
+                children: item.children.map((child) => renderItem(child, depth + 1, iconBranch))
+              }
+            )
+          }
+        )
       ] }, item.value)
     );
   };
+  const railItems = useRail ? items : [];
+  const menuItems = useRail ? items.find((item) => item.value === activeRail)?.children ?? [] : items;
+  const bodyWidth = useRail ? GNB_RAIL_WIDTH + GNB_MENU_WIDTH : GNB_MENU_WIDTH;
   const railFolded = folded && header === "fix";
-  const rootWidth = header === "full" ? "100%" : folded ? GNB_COMMON.foldWidth : GNB_MENU_WIDTH;
+  const rootWidth = header === "full" ? "100%" : folded ? GNB_COMMON.foldWidth : bodyWidth;
   const rootStyle = {
     width: rootWidth,
+    transition: `width ${GNB_FOLD_MS}ms ease-out`,
     ...header === "full" ? { gridArea: "1 / 1 / -1 / -1", pointerEvents: "none" } : { backgroundColor: C.panelBg },
     ...style
   };
+  const hideAfterSlide = (hidden) => `visibility 0s linear ${hidden ? `${GNB_FOLD_MS}ms` : "0s"}`;
   return /* @__PURE__ */ jsxRuntime.jsxs(
     "div",
     {
       ref,
-      className: cn("box-border flex h-full shrink-0 flex-col", className),
+      className: cn("box-border flex h-full shrink-0 flex-col overflow-hidden", className),
       style: rootStyle,
       "data-type": type,
       "data-header": header,
@@ -3409,30 +3520,47 @@ var SGnb = react.forwardRef(function SGnb2({
         /* @__PURE__ */ jsxRuntime.jsxs(
           "div",
           {
-            className: cn("box-border flex items-center", railFolded && "flex-col"),
+            className: "relative box-border flex shrink-0 items-center overflow-hidden",
             style: {
-              gap: railFolded ? GNB_COMMON.buttonGap : H.topGap,
-              height: railFolded ? "auto" : H.topHeight,
-              padding: railFolded ? `${GNB_COMMON.buttonGap} 0` : `0 ${H.topPaddingX}`,
+              height: H.topHeight,
+              padding: `0 ${railFolded ? GNB_RAIL.padding : H.topPaddingX}`,
               borderBottom: `1px solid ${C.topBorder}`,
               backgroundColor: C.panelBg,
               pointerEvents: "auto",
+              transition: `padding ${GNB_FOLD_MS}ms ease-out`,
               // 아이콘 버튼은 자체 ghostButton 토큰을 쓰므로, 이 색은 logo 슬롯 상속용
               color: C.itemColorDefault
             },
             children: [
-              onLauncherClick && /* @__PURE__ */ jsxRuntime.jsx(
-                SGhostButton,
+              (onLauncherClick || logo) && /* @__PURE__ */ jsxRuntime.jsxs(
+                "div",
                 {
-                  icon: "launcher",
-                  size: "xs",
-                  intent: color === "dark" ? "inverse" : "default",
-                  ariaLabel: "app launcher",
-                  onClick: onLauncherClick,
-                  className: "shrink-0"
+                  className: "absolute inset-y-0 flex items-center",
+                  style: {
+                    left: H.topPaddingX,
+                    gap: H.topGap,
+                    opacity: railFolded ? 0 : 1,
+                    transition: `opacity ${GNB_FOLD_MS}ms ease-out, ${hideAfterSlide(railFolded)}, transform ${GNB_FOLD_MS}ms ease-out`,
+                    // 메뉴와 같은 방향으로 빠지되, 좁은 레일 안에서 꼬리가 비치지 않게 페이드가 거리를 대신한다
+                    transform: railFolded ? `translateX(-${H.topPaddingX})` : "none",
+                    visibility: railFolded ? "hidden" : "visible"
+                  },
+                  children: [
+                    onLauncherClick && /* @__PURE__ */ jsxRuntime.jsx(
+                      SGhostButton,
+                      {
+                        icon: "launcher",
+                        size: "xs",
+                        intent: color === "dark" ? "inverse" : "default",
+                        ariaLabel: "app launcher",
+                        onClick: onLauncherClick,
+                        className: "shrink-0"
+                      }
+                    ),
+                    logo && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex items-center", style: { height: H.logoHeight }, children: logo })
+                  ]
                 }
               ),
-              !railFolded && logo && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex items-center", style: { height: H.logoHeight }, children: logo }),
               /* @__PURE__ */ jsxRuntime.jsx(
                 SGhostButton,
                 {
@@ -3442,30 +3570,61 @@ var SGnb = react.forwardRef(function SGnb2({
                   ariaLabel: "toggle navigation",
                   ariaPressed: folded,
                   onClick: handleFoldToggle,
-                  className: cn("shrink-0", !railFolded && "ml-auto")
+                  className: "ml-auto shrink-0"
                 }
               )
             ]
           }
         ),
-        !folded && /* @__PURE__ */ jsxRuntime.jsx(
-          "nav",
+        /* @__PURE__ */ jsxRuntime.jsxs(
+          "div",
           {
-            "aria-label": ariaLabel,
-            className: "flex flex-col overflow-y-auto",
+            className: "flex flex-row",
             style: {
-              width: GNB_MENU_WIDTH,
+              width: bodyWidth,
               alignSelf: "flex-start",
               flexGrow: 1,
               flexShrink: 1,
               flexBasis: "auto",
               minHeight: 0,
-              paddingTop: M.bodyPaddingY,
-              paddingBottom: M.bodyPaddingY,
-              backgroundColor: C.panelBg,
-              pointerEvents: "auto"
+              transform: folded ? "translateX(-100%)" : "none",
+              visibility: folded ? "hidden" : "visible",
+              transition: `transform ${GNB_FOLD_MS}ms ease-out, ${hideAfterSlide(folded)}`
             },
-            children: /* @__PURE__ */ jsxRuntime.jsx("ul", { className: "m-0 flex list-none flex-col p-0", children: items.map((item) => renderItem(item, 1)) })
+            children: [
+              useRail && // 레일도 내비게이션 landmark — nav 로 세워야 aria-label(레일)이 스크린리더에 노출된다
+              // (role 없는 ul 의 aria-label 은 영역명으로 읽히지 않는다). 메뉴 nav 와는 레이블로 구분된다.
+              /* @__PURE__ */ jsxRuntime.jsx(
+                "nav",
+                {
+                  "aria-label": `${ariaLabel} rail`,
+                  className: "flex shrink-0 flex-col overflow-y-auto",
+                  style: {
+                    width: GNB_RAIL_WIDTH,
+                    padding: GNB_RAIL.padding,
+                    borderRight: `1px solid ${C.topBorder}`,
+                    backgroundColor: C.panelBg,
+                    pointerEvents: "auto"
+                  },
+                  children: /* @__PURE__ */ jsxRuntime.jsx("ul", { className: "m-0 flex list-none flex-col p-0", style: { gap: GNB_RAIL.gap }, children: railItems.map(renderRailItem) })
+                }
+              ),
+              /* @__PURE__ */ jsxRuntime.jsx(
+                "nav",
+                {
+                  "aria-label": ariaLabel,
+                  className: "flex shrink-0 flex-col overflow-y-auto",
+                  style: {
+                    width: GNB_MENU_WIDTH,
+                    paddingTop: M.bodyPaddingY,
+                    paddingBottom: M.bodyPaddingY,
+                    backgroundColor: C.panelBg,
+                    pointerEvents: "auto"
+                  },
+                  children: /* @__PURE__ */ jsxRuntime.jsx("ul", { className: "m-0 flex list-none flex-col p-0", children: menuItems.map((item) => renderItem(item, 1)) })
+                }
+              )
+            ]
           }
         )
       ]