sellmate-design-system-react 4.1.0 → 4.2.0

package/AGENTS.md

@@ -150,7 +150,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 
 ### 2-2. 간격 (spacing)
 
-- **간격 유틸리티는 `sd-` 접두를 붙인다** — `gap-sd-8`, `p-sd-20`, `mt-sd-12`. 숫자 = px 다.
+- **간격 유틸리티는 `sd-` 접두를 붙인다** — `gap-sd-8`, `p-sd-16`, `mt-sd-12`. 숫자 = px 다.
   접두를 빼면 Tailwind 기본 스케일이 적용된다(`gap-8` = 32px). 접두는 속성 뒤, 숫자 앞에 온다.
 - 스케일: `2 4 6 8 10 12 16 19 20 22 24 28 32 36 40 44 48 56 60 62 80`
 - 형제 요소 간격은 margin 대신 부모의 `flex`/`grid` + `gap-sd-*`으로 잡는다.
@@ -158,7 +158,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 
 | 상황 | 값 |
 | --- | --- |
-| **페이지 콘텐츠 패딩** | **`p-sd-20`** |
+| **페이지 콘텐츠 패딩** | **16px — `SPage` 가 `--cmp-pageBody-padding` 으로 이미 넣는다.** 직접 주지 않는다 (덮어쓰면 토큰이 바뀌어도 안 따라간다). `SPage` 밖에서 같은 패딩이 필요하면 `p-sd-16` |
 | **섹션 ↔ 섹션** | **`gap-sd-12`** |
 | **페이지 내 블록 ↔ 블록** (헤더·필터·툴바·테이블 사이) | **`gap-sd-12`** |
 | 요소 ↔ 요소 | **기본 `gap-sd-8`** (`--sys-space-stack-gap-element-normal`) · 타이트 `gap-sd-4`(`-tight`) · 여유 `gap-sd-12`(`-relaxed`) / `gap-sd-16`(`-wide`) |
@@ -338,7 +338,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 - 작은 창이 아니라 **화면 하나가 통째로** 들어간다 — 검색 필터·테이블·페이지네이션이 그대로 있는 목록(`엑셀 파일 관리`), 헤더 카드·탭이 있는 상세(`이동 오더 상세`).
 - 상세를 팝업으로 여는 이유는 **목록을 떠나지 않고 여러 건을 번갈아 보기** 위해서다. 단 상세가 **항상** 팝업인 것은 아니고, 데이터 양이 많을 때 팝업을 쓴다.
 - 구조는 헤더(제목 중앙) + 본문 + 푸터다. **확정할 작업이 있으면 푸터에 `저장`, 조회만이면 `useFooter={false}`** 로 푸터를 없앤다.
-- 본문에는 패딩이 없다 — 콘텐츠가 여백을 담당한다. 팝업 안도 일반 페이지와 같은 규칙(§4)을 따른다: 패딩 `p-sd-20`, 블록 간격 `gap-sd-12`, 표는 `SKeyValueTable` / `STable`.
+- 본문에는 패딩이 없다 — 콘텐츠가 여백을 담당한다. 팝업 안도 일반 페이지와 같은 규칙(§4)을 따른다: 패딩 `p-sd-16`(`SPage` 가 아니라 직접 준다), 블록 간격 `gap-sd-12`, 표는 `SKeyValueTable` / `STable`.
 
 ```tsx
 // 1) 목록에서 별도 창을 연다 — 창 크기 = 콘텐츠 크기
@@ -354,7 +354,7 @@ function openDetailPopup(orderId: string) {
 export default function TransferOrderPopupPage() {
   return (
     <SPopup popupTitle="이동 오더 상세" useFooter={false}>
-      <div className="flex flex-col gap-sd-12 p-sd-20">
+      <div className="flex flex-col gap-sd-12 p-sd-16">
         <SSectionHeaderCard>…</SSectionHeaderCard>
         <STabs value={tab} tabs={TABS} onValueChange={setTab} />
         <STable columns={columns} rows={rows} rowKey="id" />
@@ -610,12 +610,41 @@ export default function AppShell({ children }: { children: React.ReactNode }) {
     <SLayout type="box" header="fix">
       {/* type/header/folded 는 SLayout 에만 준다 — SGnb 는 context 에서 읽는다 */}
       <SGnb items={MENU} value={current} onValueChange={navigate} logo={<Logo />} />
-      <SPage background="frame" className="p-sd-20">{children}</SPage>
+      {/* 콘텐츠 패딩(16px)은 SPage 가 토큰으로 넣는다 — p-sd-* 로 덮어쓰지 않는다 */}
+      <SPage background="frame">{children}</SPage>
     </SLayout>
   );
 }
 ```
 
+**상단바 배치는 `header` 가 정한다.** 요소 순서가 달라지므로 슬롯을 채우기 전에 어느 쪽인지부터 정한다.
+
+| `header` | 상단바 배치 | 로고 폭 | `topContent` |
+| --- | --- | --- | --- |
+| `"fix"` (기본) | `[런처 · 로고 … 폴드]` — 상단바가 GNB 컬럼 안에 있고 폴드가 컬럼 오른쪽 끝 | 내용 폭 | **렌더되지 않는다** (놓을 자리가 없다) |
+| `"full"` | `[런처 · 폴드 · 로고 · topContent]` — 상단바가 화면 전폭 | **140px 고정** | 로고 오른쪽 남는 폭 전체 |
+
+- `topContent` 는 상단바 로고 오른쪽 슬롯이다. 전역 검색·계정 메뉴·알림처럼 **모든 페이지에 공통인 것만** 넣는다. 페이지별 액션은 여기가 아니라 §4-2 의 `STableBar` 로 간다.
+- 슬롯이 남는 폭을 통째로 받으므로 **정렬은 안에서 직접 잡는다** (좌측 정렬 + 우측은 `ml-auto`).
+- `header="full"` 에서 로고 자리는 140px 로 고정된다 — 로고 내용이 바뀌어도 `topContent` 시작점이 흔들리지 않게 하기 위함이다. 로고가 그보다 넓으면 잘리므로 이 폭에 맞춰 준비한다.
+
+```tsx
+<SLayout type="box" header="full">
+  <SGnb
+    items={MENU} value={current} onValueChange={navigate}
+    logo={<Logo />}
+    topContent={
+      /* 남는 폭 전체를 받는다 — 왼쪽은 그대로, 오른쪽 끝은 ml-auto */
+      <div className="flex w-full items-center gap-sd-8">
+        <SInput value={keyword} onValueChange={setKeyword} placeholder="통합 검색" />
+        <SButton size="sm" color="neutral" outline label="내 계정" className="ml-auto" onClick={openAccount} />
+      </div>
+    }
+  />
+  <SPage background="frame">{children}</SPage>
+</SLayout>
+```
+
 ### 4-2. 목록 페이지 (필터 + 테이블)
 
 구조: **페이지 헤더(제목 + 가이드 링크) → 필터(`SKeyValueTable`) → `STableBar` → `STable`**
@@ -874,7 +903,7 @@ export default function ProductDetailPage() {
 - [ ] 간격이 전부 `sd-` 접두 스케일 값인가 (`gap-13`·`gap-sd-13` ❌ → `gap-sd-12` ✅)
 - [ ] 본문이 12px(`typo-body-sm-default`)인가 (14px 본문 ❌)
 - [ ] 텍스트 회색 위계를 순차 적용했는가 (기본 → `text-fg-secondary` → `text-fg-tertiary`, 단계 건너뛰기 ❌)
-- [ ] 페이지 패딩이 `p-sd-20`, 블록·섹션 간격이 `gap-sd-12` 인가 (`gap-sd-16`/`gap-sd-24` ❌)
+- [ ] `SPage` 의 기본 패딩(16px)을 `p-sd-*` 로 덮어쓰지 않았는가, 블록·섹션 간격이 `gap-sd-12` 인가 (`gap-sd-16`/`gap-sd-24` ❌)
 - [ ] 같은 컴포넌트를 나열할 때 §2-2 그룹 간격을 썼는가 (체크박스 가로 `gap-sd-24` 등)
 - [ ] 페이지가 §4의 표준 골격에서 시작했는가
 - [ ] 필터·폼·상세 정보를 `SKeyValueTable` 로 만들었는가 (컨트롤을 `div` 로 나열하지 않았는가)

package/dist/components/SGnb/README.md

@@ -15,7 +15,8 @@
 | `useRail?` | `boolean` | — | 좌측 레일 사용 여부. 켜면 items 의 첫 depth 가 아이콘+라벨 버튼의 세로 레일로 서고, 선택된 레일 아이템의 children 이 오른쪽 메뉴 패널에 깔린다. 미지정 시 SLayout 의 useRail 을 따른다. children 없는 레일 아이템이 활성이면 메뉴 패널은 렌더되지 않고 레일만 남는다. |
 | `value?` | `string` | `''` | 현재 선택된 아이템 value |
 | `folded?` | `boolean` | — | 접힘(레일) 상태. 미지정 시 SLayout 의 folded 를 따른다. |
-| `logo?` | `ReactNode` | — | 상단바 로고 영역 (slot) |
+| `logo?` | `ReactNode` | — | 상단바 로고 영역 (slot). header="full" 이면 폭이 140px 로 고정된다. |
+| `topContent?` | `ReactNode` | — | 상단바 로고 오른쪽 슬롯 (검색·액션 등). 로고와 16px 띄고 남는 폭을 모두 차지하므로 안에서 자유롭게 정렬한다. 상단바가 전폭인 header="full" 에서만 렌더된다 (fix 는 상단바가 좁은 GNB 컬럼 안이라 놓을 자리가 없다). |
 | `railFooter?` | `ReactNode` | — | 레일 하단 고정 슬롯. 레일 아이템이 많아 넘치면 아이템 목록(ul)만 스크롤되고 이 슬롯은 레일 하단에 붙어 고정된다. useRail 일 때만 렌더된다. |
 | `menuFooter?` | `ReactNode` | — | 메뉴 하단 고정 슬롯. 메뉴 아이템이 많아 넘치면 메뉴 목록(ul)만 스크롤되고 이 슬롯은 메뉴 하단에 붙어 고정된다. 메뉴가 렌더될 때만(showMenu) 나타난다. |
 | `foldedFooter?` | `ReactNode` | — | 접힘(fix 레일) 하단 고정 슬롯. 접으면 본문이 빠져나가며 rail/menu footer 도 사라지므로, 48px 폴드 레일 바닥에 붙는 별도 슬롯이다. header="fix" 로 접혔을 때만 나타난다. |

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

@@ -30,8 +30,14 @@ export interface SGnbProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color'>
     onFoldChange?: (folded: boolean) => void;
     /** 앱런처(그리드) 버튼 클릭. 미지정 시 런처 버튼을 렌더하지 않는다. 접힘 레일(fix)에는 폴드 버튼만 남으므로 표시되지 않는다. */
     onLauncherClick?: () => void;
-    /** 상단바 로고 영역 (slot) */
+    /** 상단바 로고 영역 (slot). header="full" 이면 폭이 140px 로 고정된다. */
     logo?: ReactNode;
+    /**
+     * 상단바 로고 오른쪽 슬롯 (검색·액션 등). 로고와 16px 띄고 남는 폭을 모두 차지하므로
+     * 안에서 자유롭게 정렬한다. 상단바가 전폭인 header="full" 에서만 렌더된다
+     * (fix 는 상단바가 좁은 GNB 컬럼 안이라 놓을 자리가 없다).
+     */
+    topContent?: ReactNode;
     /**
      * 레일 하단 고정 슬롯. 레일 아이템이 많아 넘치면 아이템 목록(ul)만 스크롤되고
      * 이 슬롯은 레일 하단에 붙어 고정된다. useRail 일 때만 렌더된다.

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

@@ -115,6 +115,18 @@ export declare const GNB_EXPAND_MS = 200;
  * header="full" 에서 SLayout 이 "메뉴 오른쪽 = 페이지" 영역을 잡을 때도 이 값을 쓴다.
  */
 export declare const GNB_MENU_WIDTH = 240;
+/**
+ * header="full" 상단바의 로고 슬롯 고정 폭(토큰 없음 → 상수).
+ * 전폭 상단바에서는 로고 오른쪽에 topContent 슬롯이 이어지므로, 로고 내용이 바뀌어도
+ * 그 시작점이 흔들리지 않도록 자리를 못 박는다. fix 는 상단바가 GNB 컬럼 안이라 내용 폭을 따른다.
+ */
+export declare const GNB_FULL_LOGO_WIDTH = 140;
+/**
+ * 상단바에서 아이콘 버튼끼리 붙는 간격(px, 디자인 스펙 — 전용 토큰 없음).
+ * header="full" 의 런처↔폴드가 여기 해당한다. 슬롯(로고·topContent)과의 간격은
+ * 이보다 넓은 --cmp-gnb-top-gap 을 쓴다.
+ */
+export declare const GNB_TOP_ICON_GAP = 8;
 /**
  * useRail 에서 value 를 품은 첫 depth(레일) 아이템의 value.
  * value 자체가 레일 아이템이면 그 값을, 어디에도 없으면 undefined 를 반환한다.

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

@@ -1,2 +1,2 @@
 export { SGnb, type SGnbProps } from './SGnb';
-export { GNB_HEADER, GNB_MENU, GNB_COLORS, GNB_COMMON, GNB_FOLD_MS, GNB_MENU_WIDTH, GNB_RAIL, GNB_RAIL_WIDTH, findGnbAncestors, findGnbRailValue, type SGnbType, type SGnbHeader, type SGnbColor, type SGnbMenuItem, } from './gnb.config';
+export { GNB_HEADER, GNB_MENU, GNB_COLORS, GNB_COMMON, GNB_FOLD_MS, GNB_FULL_LOGO_WIDTH, GNB_MENU_WIDTH, GNB_RAIL, GNB_RAIL_WIDTH, findGnbAncestors, findGnbRailValue, type SGnbType, type SGnbHeader, type SGnbColor, type SGnbMenuItem, } from './gnb.config';

package/dist/index.cjs

@@ -6961,6 +6961,8 @@ var GNB_RAIL_WIDTH = 68;
 var GNB_FOLD_MS = 200;
 var GNB_EXPAND_MS = 200;
 var GNB_MENU_WIDTH = 240;
+var GNB_FULL_LOGO_WIDTH = 140;
+var GNB_TOP_ICON_GAP = 8;
 function findGnbRailValue(items, value) {
   if (items.some((item) => item.value === value)) return value;
   return findGnbAncestors(items, value)[0];
@@ -7065,6 +7067,7 @@ var SGnb = /* @__PURE__ */ react.forwardRef(function SGnb2({
   onFoldChange,
   onLauncherClick,
   logo,
+  topContent,
   railFooter,
   menuFooter,
   foldedFooter,
@@ -7296,13 +7299,67 @@ var SGnb = /* @__PURE__ */ react.forwardRef(function SGnb2({
     ...style
   };
   const hideAfterSlide = (hidden) => `visibility 0s linear ${hidden ? `${GNB_FOLD_MS}ms` : "0s"}`;
-  const foldInline = !!logo;
   const sideFoldStyle = {
     opacity: railFolded ? 0 : 1,
     position: railFolded ? "absolute" : "static",
     visibility: railFolded ? "hidden" : "visible",
     transition: `opacity ${GNB_FOLD_MS}ms ease-out, ${hideAfterSlide(railFolded)}`
   };
+  const launcherButton = onLauncherClick ? /* @__PURE__ */ jsxRuntime.jsx(
+    SGhostButton,
+    {
+      icon: "launcher",
+      size: "xs",
+      intent: color === "dark" ? "inverse" : "default",
+      ariaLabel: "app launcher",
+      onClick: onLauncherClick,
+      className: "shrink-0",
+      style: { ...sideFoldStyle, marginRight: header === "fix" ? H.topGap : GNB_TOP_ICON_GAP }
+    },
+    "launcher"
+  ) : null;
+  const foldButton = /* @__PURE__ */ jsxRuntime.jsx(
+    SGhostButton,
+    {
+      icon: "sidebar",
+      size: "xs",
+      intent: color === "dark" ? "inverse" : "default",
+      ariaLabel: "toggle navigation",
+      ariaPressed: folded,
+      onClick: handleFoldToggle,
+      className: cn("shrink-0", header === "fix" && "ml-auto")
+    },
+    "fold"
+  );
+  const logoBox = logo ? /* @__PURE__ */ jsxRuntime.jsx(
+    "div",
+    {
+      className: "flex shrink-0 items-center",
+      style: {
+        height: H.logoHeight,
+        ...header === "full" ? (
+          // full 은 전폭이라 로고 자리가 고정이다 — 폭 140px(디자인 스펙, 전용 토큰 없음)로 못 박아
+          // 로고 내용이 바뀌어도 오른쪽 topContent 시작점이 흔들리지 않게 한다.
+          { width: GNB_FULL_LOGO_WIDTH, marginLeft: H.topGap }
+        ) : (
+          // fix 는 폴드가 ml-auto 로 밀려나므로(margin-left 를 못 쓴다) 로고 오른쪽에 최소 간격을 둔다
+          { marginRight: H.topGap }
+        ),
+        ...sideFoldStyle
+      },
+      children: logo
+    },
+    "logo"
+  ) : null;
+  const topContentBox = header === "full" && topContent ? /* @__PURE__ */ jsxRuntime.jsx(
+    "div",
+    {
+      className: "flex min-w-0 flex-1 items-center",
+      style: { marginLeft: H.topGap },
+      children: topContent
+    },
+    "topContent"
+  ) : null;
   return /* @__PURE__ */ jsxRuntime.jsxs(
     "div",
     {
@@ -7320,8 +7377,9 @@ var SGnb = /* @__PURE__ */ react.forwardRef(function SGnb2({
             className: "relative box-border flex shrink-0 items-center overflow-hidden",
             style: {
               height: H.topHeight,
-              // 인라인 간격은 컨테이너 gap 대신 각 요소 margin 으로 준다 — 런처↔폴드(8px)와
-              // 폴드↔로고(top-gap)를 다르게 두기 위함. 접히면 런처·로고가 흐름에서 빠져 margin 도 무의미해진다.
+              // 간격은 컨테이너 gap 대신 각 요소 margin 으로 준다 — 순서가 header 마다 달라
+              // 이웃 쌍마다 값이 다르기 때문(위 launcherButton/logoBox 주석).
+              // 접히면 런처·로고가 흐름에서 빠져 margin 도 무의미해진다.
               padding: `0 ${railFolded ? GNB_RAIL.padding : H.topPaddingX}`,
               borderBottom: `1px solid ${C.topBorder}`,
               backgroundColor: C.panelBg,
@@ -7330,90 +7388,16 @@ var SGnb = /* @__PURE__ */ react.forwardRef(function SGnb2({
               // 아이콘 버튼은 자체 ghostButton 토큰을 쓰므로, 이 색은 logo 슬롯 상속용
               color: C.itemColorDefault
             },
-            children: foldInline ? (
-              // 런처(있을 때)·폴드·로고를 흐름에 나란히 둔다 → 폴드 버튼이 (런처와) 로고 사이에 선다.
-              // 접히면 런처·로고가 페이드하며 흐름에서 빠지고(sideFoldStyle), 폴드 버튼만 남아 레일 가운데에 선다.
-              /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
-                onLauncherClick && /* @__PURE__ */ jsxRuntime.jsx(
-                  SGhostButton,
-                  {
-                    icon: "launcher",
-                    size: "xs",
-                    intent: color === "dark" ? "inverse" : "default",
-                    ariaLabel: "app launcher",
-                    onClick: onLauncherClick,
-                    className: "shrink-0",
-                    style: { ...sideFoldStyle, marginRight: "8px" }
-                  }
-                ),
-                /* @__PURE__ */ jsxRuntime.jsx(
-                  SGhostButton,
-                  {
-                    icon: "sidebar",
-                    size: "xs",
-                    intent: color === "dark" ? "inverse" : "default",
-                    ariaLabel: "toggle navigation",
-                    ariaPressed: folded,
-                    onClick: handleFoldToggle,
-                    className: "shrink-0"
-                  }
-                ),
-                /* @__PURE__ */ jsxRuntime.jsx(
-                  "div",
-                  {
-                    className: "flex shrink-0 items-center",
-                    style: { height: H.logoHeight, marginLeft: H.topGap, ...sideFoldStyle },
-                    children: logo
-                  }
-                )
-              ] })
-            ) : (
-              // 런처·로고는 좌측 그룹(흐름에서 빼 폭 축소 중 폴드 버튼을 밀어내지 않는다),
-              // 폴드 버튼은 우측 끝(ml-auto)이라 폭·패딩이 줄면 저절로 레일 가운데에 선다.
-              /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
-                (onLauncherClick || logo) && /* @__PURE__ */ jsxRuntime.jsxs(
-                  "div",
-                  {
-                    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 })
-                    ]
-                  }
-                ),
-                /* @__PURE__ */ jsxRuntime.jsx(
-                  SGhostButton,
-                  {
-                    icon: "sidebar",
-                    size: "xs",
-                    intent: color === "dark" ? "inverse" : "default",
-                    ariaLabel: "toggle navigation",
-                    ariaPressed: folded,
-                    onClick: handleFoldToggle,
-                    className: "ml-auto shrink-0"
-                  }
-                )
-              ] })
-            )
+            children: header === "fix" ? /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+              launcherButton,
+              logoBox,
+              foldButton
+            ] }) : /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+              launcherButton,
+              foldButton,
+              logoBox,
+              topContentBox
+            ] })
           }
         ),
         /* @__PURE__ */ jsxRuntime.jsxs(
@@ -13470,6 +13454,7 @@ exports.COLOR_KEYS = COLOR_KEYS;
 exports.GNB_COLORS = GNB_COLORS;
 exports.GNB_COMMON = GNB_COMMON;
 exports.GNB_FOLD_MS = GNB_FOLD_MS;
+exports.GNB_FULL_LOGO_WIDTH = GNB_FULL_LOGO_WIDTH;
 exports.GNB_HEADER = GNB_HEADER;
 exports.GNB_MENU = GNB_MENU;
 exports.GNB_MENU_WIDTH = GNB_MENU_WIDTH;