sellmate-design-system-react 9.0.0-beta.40 → 9.0.0-beta.41

package/dist/llms.txt

@@ -721,8 +721,8 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 
 - 작은 창이 아니라 **화면 하나가 통째로** 들어간다 — 검색 필터·테이블·페이지네이션이 그대로 있는 목록(`엑셀 파일 관리`), 헤더 카드·탭이 있는 상세(`이동 오더 상세`).
 - 상세를 팝업으로 여는 이유는 **목록을 떠나지 않고 여러 건을 번갈아 보기** 위해서다. 단 상세가 **항상** 팝업인 것은 아니고, 데이터 양이 많을 때 팝업을 쓴다.
-- 구조는 헤더(제목 중앙) + 본문이고 **푸터는 기본으로 없다**. 조회만 하는 팝업은 그대로 두고, **확정할 작업이 있을 때만 `useFooter` 로 푸터를 켜서 `submitButton` 에 `저장`** 을 둔다.
-- **본문 패딩은 `SPopup` 이 토큰으로 넣는다. 직접 주지 않는다** (`p-sd-*` 로 덮어쓰면 토큰이 바뀌어도 안 따라간다). 표를 가장자리까지 채우는 등 콘텐츠가 여백을 직접 다뤄야 할 때만 `noPadding` 으로 끈다.
+- 구조는 헤더(제목 중앙) + 본문이고 **푸터는 기본으로 없다**. 조회만 하는 팝업은 그대로 두고, **확정할 작업이 있을 때만 `showFooter` 로 푸터를 켜서 `submitButton` 에 `저장`** 을 둔다.
+- **본문 패딩은 `SPopup` 이 토큰으로 넣는다. 직접 주지 않는다** (`p-sd-*` 로 덮어쓰면 토큰이 바뀌어도 안 따라간다). 표를 가장자리까지 채우는 등 콘텐츠가 여백을 직접 다뤄야 할 때만 `padding="none"` 으로 끈다.
 - 그 밖에는 팝업 안도 일반 페이지와 같은 규칙(§4)을 따른다: 블록 간격 `gap-sd-12`, 표는 `SKeyValueTable` / `STable`.
 
 ```tsx
@@ -1304,7 +1304,7 @@ const columns: STableColumn[] = [
 - 모델은 항상 **첫 패널**(`SSplitter.Before`) 크기다. 사이드가 기준인 화면이면 사이드를 `Before` 에 둔다.
 - 앱 셸의 GNB 폭은 `SGnb` 가 소유한다. `SLayout`/`SGnb` 를 `SSplitter` 로 감싸지 않는다 — **GNB 폭을 끌 수 있게 하려면 `SGnb` 에 `resizable` 을 준다**(§4-1).
 
-**Quasar `q-splitter` 에서 옮겨올 때** — `unit` · `limits` · `emitImmediately` 는 이름과 뜻이 같고, 나머지는 아래처럼 바뀐다. `emitImmediately` 를 주지 않으면 **드래그를 놓는 순간 한 번만** `onValueChange` 가 온다.
+**Quasar `q-splitter` 에서 옮겨올 때** — `unit` · `limits` · `updateWhileDragging` 는 이름과 뜻이 같고, 나머지는 아래처럼 바뀐다. `updateWhileDragging` 를 주지 않으면 **드래그를 놓는 순간 한 번만** `onValueChange` 가 온다.
 
 | q-splitter | SSplitter |
 | --- | --- |
@@ -1459,12 +1459,12 @@ const [from, setFrom] = useState<string | null>(null);
 - **항목 하나의 속성을 나열하는 것은 목록이 아니다.** `라벨: 값` 이 세로로 쌓이는 것은 `SKeyValueTable` 이다 (§4-4).
 - `SList` 는 레이아웃만 담당한다. depth 별 단일 펼침이 필요하면 `SExpansionList` 다 (§3-7-7).
 - **`SList` 의 자식은 `SListItem` 을 권장한다.** 다른 자식도 그대로 렌더되지만, 펼치는 항목은 `SExpansionList` + `SExpansionItem` 이, 끌어서 순서를 바꾸는 항목은 `SDraggableList` + `SDraggableItem` 이 여닫힘·정렬 동작까지 함께 관리하므로 그쪽을 쓴다 (§3-7-7).
-- **항목 사이 구분선은 리스트가 알아서 그린다.** `SListItem`·`SExpansionItem`·`SDraggableItem` 셋 다 스스로 구분선을 그리지 않는다. `SList`·`SExpansionList`·`SDraggableList` 가 자식 **사이에** 구분선을 넣으므로 아이템에 `border-b` 를 직접 붙이지 않고, 켜는 prop 도 따로 없다. 마지막 항목 아래에는 선이 남지 않는다. 테두리형(`bordered`)은 테두리가 구분 역할을 하므로 리스트가 구분선을 빼고, `useGap` 으로 띄운다 — `useGap` 을 준 목록에도 구분선은 들어가지 않는다.
+- **항목 사이 구분선은 리스트가 알아서 그린다.** `SListItem`·`SExpansionItem`·`SDraggableItem` 셋 다 스스로 구분선을 그리지 않는다. `SList`·`SExpansionList`·`SDraggableList` 가 자식 **사이에** 구분선을 넣으므로 아이템에 `border-b` 를 직접 붙이지 않고, 켜는 prop 도 따로 없다. 마지막 항목 아래에는 선이 남지 않는다. 테두리형(`bordered`)은 테두리가 구분 역할을 하므로 리스트가 구분선을 빼고, `gap` 으로 띄운다 — `gap` 을 준 목록에도 구분선은 들어가지 않는다.
 - **`SListItem` 은 기본이 표시 전용이다.** 눌러서 이동·선택하게 하려면 `clickable` 을 준다 — hover·`selected`·`interaction="chevron"` 표현이 전부 여기에 딸려 있어서, `clickable` 없이 `selected` 만 주면 선택 표시가 나오지 않는다. `SExpansionList` 는 자식 아이템을 알아서 클릭 가능하게 만들어 이 함정을 막아 준다 — 선택 상태 자체는 앱이 든다 (§3-7-7).
 
 ```tsx
 ✅ <SList><SListItem title="일반 문의" />…</SList>              {/* 줄로 구분되는 목록 — 구분선은 자동 */}
-✅ <SList useGap><SListItem title="일반 문의" bordered />…</SList>  {/* 카드처럼 떨어진 목록 */}
+✅ <SList gap><SListItem title="일반 문의" bordered />…</SList>  {/* 카드처럼 떨어진 목록 */}
 ✅ <SListItem title="일반 문의" clickable selected onClick={…} />   {/* 눌러서 고르는 목록 */}
 ❌ <SList><SListItem title="일반 문의" className="border-b" />…</SList>  {/* 구분선을 직접 붙이지 않는다 */}
 ❌ <SList><><SListItem title="일반 문의" /><SListItem title="결제 문의" /></></SList>  {/* Fragment 로 묶으면 그 안쪽은 구분되지 않는다 */}
@@ -1610,6 +1610,7 @@ export default function AppShell({
   header?: SPageHeaderProps;
   scrollEndSpacing?: boolean;
   contentHeight?: SPageContentHeight;
+  contentWidth?: SPageContentWidth;
 }) {
   return (
     <SLayout type="box" header="fix">
@@ -1621,7 +1622,13 @@ export default function AppShell({
       {/* 콘텐츠 패딩은 SPage 가 토큰으로 넣는다 — p-sd-* 로 덮어쓰지 않는다 */}
       {/* 높이 모드는 페이지가 정한다 — 대부분 contentHeight="fill" 이다 (§2-2) */}
       {/* 스크롤 끝 여백도 SPage 가 넣는다. 페이지가 실제로 스크롤되는 화면에서만 켠다 */}
-      <SPage background="frame" scrollEndSpacing={scrollEndSpacing} contentHeight={contentHeight}>
+      {/* 가로 폭 모드도 페이지가 정한다 — 넓은 창에서 본문을 늘릴지 최소 폭으로 세울지 */}
+      <SPage
+        background="frame"
+        scrollEndSpacing={scrollEndSpacing}
+        contentHeight={contentHeight}
+        contentWidth={contentWidth}
+      >
         {children}
       </SPage>
     </SLayout>
@@ -1637,7 +1644,7 @@ export default function AppShell({
 
 **페이지 헤더 사용 규칙 — 이 앱에서는 값이 아니라 값의 일관성이 규칙이다.**
 
-- **`fix` 는 앱 전체에서 하나로 고정한다.** 어떤 페이지는 `fix`(높이 고정 바), 다른 페이지는 기본형으로 섞어 쓰지 않는다. 프로젝트에서 하나를 고르면(예: 전부 `fix`) 모든 페이지 헤더가 그 값을 쓴다.
+- **`variant` 는 필수이고, 앱 전체에서 하나로 고정한다.** 어떤 페이지는 `"bar"`(높이 고정 + 하단 구분선), 다른 페이지는 `"plain"`(최소 높이) 로 섞어 쓰지 않는다. 프로젝트에서 하나를 고르면(예: 전부 `"bar"`) 모든 페이지 헤더가 그 값을 쓴다. **기본값이 없는 것도 이 규칙 때문이다** — 기본값이 있으면 안 준 페이지만 조용히 다른 모양이 되어 메뉴를 옮길 때마다 제목 줄이 튄다. 셸을 한 번 감싸 쓰면 지정하는 자리는 `AppShell` 한 곳이다. `SLayout` 의 `header`(`"fix" | "full"`)와는 다른 축이다 — 그쪽은 상단바가 GNB 컬럼 안에 있는지 화면 전폭인지를 정한다.
 - **`slot`·`onBack` 도 페이지 성격이 실제로 다른 경우가 아니면 있는 대로 통일한다.** "목록 페이지엔 없고 상세·등록 페이지엔 있다"처럼 화면 종류에 따라 갈리는 것은 허용되지만, 같은 종류의 화면끼리는 임의로 넣었다 뺐다 하지 않는다.
 - **`slot` 은 `ReactNode` 를 그대로 받지만, 원칙은 `size="sm"` 버튼 위주로만 채운다.** `STextLink`·복잡한 커스텀 마크업을 슬롯에 넣지 않는다 — 그 이상이 필요하면 페이지 헤더가 아니라 §4-2 의 `STableBar` 처럼 본문 쪽 액션 자리를 쓴다.
 
@@ -1650,7 +1657,7 @@ const [scrolled, setScrolled] = useState(false);
 
 {/* 헤더는 자기 흰 면을 스스로 칠한다 — 감싸는 쪽은 본문이 놓일 면만 정하면 된다 */}
 <div className="flex h-full min-h-0 flex-col bg-[var(--sys-color-bg-frame)]">
-  <SPageHeader title="상품 목록" subText="판매 중인 상품을 관리합니다." scrolled={scrolled} />
+  <SPageHeader variant="plain" title="상품 목록" subText="판매 중인 상품을 관리합니다." scrolled={scrolled} />
   {/* 스크롤을 앱이 쥐므로 scrolled 도 앱이 넣는다 — 패딩은 SPage 가 없으니 여기서 준다 */}
   <div
     className="min-h-0 flex-1 overflow-auto p-sd-16"
@@ -1687,7 +1694,20 @@ import { SModalOutlet } from 'sellmate-design-system-react';
 
 **최소 너비는 `SLayout` 이 보장한다 — 앱이 `min-w-*` 를 직접 주지 않는다.** 창이 최소 너비(`SLAYOUT_MIN_WIDTH`, GNB 포함한 전체 기준)보다 좁아지면 GNB·상단바는 제자리에 남고 **`SPage` 안에만 가로 스크롤이 생긴다.** 문서(브라우저 창)에는 가로 스크롤이 생기지 않는다. 그래서 셸을 감싸는 요소에 `min-width` 나 `overflow-x` 를 걸지 않는다 — 걸면 창 전체가 스크롤되어 GNB 가 화면 밖으로 밀린다.
 
-**셸의 `SPage` 는 모든 페이지가 공유하므로, 페이지마다 달라지는 것은 페이지가 셸에 알려야 한다.** 위처럼 프레임 컴포넌트가 `contentHeight` · `scrollEndSpacing` 을 받아 그대로 넘긴다.
+**창이 최소 너비보다 넓을 때 본문을 어떻게 세울지는 `SPage` 의 `contentWidth` 가 정한다 — 폭을 직접 계산하지 않는다.** 넓은 모니터에서 본문이 끝까지 늘어나 성기어지는 화면이 있으므로 세 가지 중 하나를 고른다.
+
+| `contentWidth` | 넓은 창에서 | 쓰는 곳 |
+| --- | --- | --- |
+| `"full"` (기본) | 남는 폭을 본문이 다 쓴다 | 표·목록처럼 가로를 넓게 쓸수록 정보가 더 들어가는 화면 |
+| `"fixed"` | 최소 너비일 때의 본문 폭으로 고정, 왼쪽 정렬 (남는 폭은 오른쪽) | 시안 폭 그대로 세우되 왼쪽 기준을 유지할 화면 |
+| `"fixedCenter"` | 같은 폭으로 고정, 가운데 정렬 (남는 폭은 좌우) | 폼·상세처럼 가로를 넓게 써도 얻을 것이 없는 화면 |
+
+- **고정 폭에 숫자를 쓰지 않는다.** `max-w-*` 나 `mx-auto` 로 흉내 내면 GNB 폭·접힘이 반영되지 않아 시안과 어긋난다. 고정 폭은 "창이 최소 너비일 때의 본문 폭"이고 `SPage` 가 GNB 상태까지 반영해 계산한다.
+- **창이 최소 너비보다 좁아지면 세 모드가 모두 같다** — 남는 폭이 없으므로 위 문단대로 `SPage` 안에만 가로 스크롤이 생긴다.
+- 같은 열의 `SPageHeader` 는 자동으로 같은 폭·정렬을 따른다 — 제목 줄에 별도로 주지 않는다. 헤더의 흰 면·구분선은 늘 전폭이다.
+- **같은 종류의 화면끼리는 값을 통일한다** (헤더 `fix` 와 같은 이유). 목록 페이지마다 `full`·`fixedCenter` 가 섞이면 메뉴를 옮길 때마다 본문 폭이 튄다.
+
+**셸의 `SPage` 는 모든 페이지가 공유하므로, 페이지마다 달라지는 것은 페이지가 셸에 알려야 한다.** 위처럼 프레임 컴포넌트가 `contentHeight` · `scrollEndSpacing` · `contentWidth` 를 받아 그대로 넘긴다.
 
 **대부분의 페이지는 `contentHeight="fill"` 이다** — 본문이 창을 꽉 채우고 스크롤은 각 영역 안에서 일어나는 것이 표준이다(§2-2). 블록의 높이가 정해져 있고 그 높이가 창보다 커서 페이지 자체가 스크롤돼야 하는 화면에서만 `contentHeight="auto"`(기본값) + `scrollEndSpacing` 을 켠다.
 
@@ -1723,14 +1743,14 @@ import { SModalOutlet } from 'sellmate-design-system-react';
 </SLayout>
 ```
 
-**메뉴 목록과 함께 스크롤되면 안 되는 것은 `SGnb` 의 위아래 고정 슬롯에 둔다.** 레일과 메뉴에 각각 위(`railTop`·`menuTop`)와 아래(`railFooter`·`menuFooter`) 슬롯이 있다. 아이템이 많아 넘치면 **목록만 스크롤되고 이 슬롯들은 제자리에 남는다** — 메뉴 검색, 워크스페이스 전환, 계정 행처럼 항상 보여야 하는 것이 여기 온다. 레일 슬롯은 `useRail` 일 때만, 메뉴 슬롯은 깔 메뉴가 있을 때만 렌더된다.
+**메뉴 목록과 함께 스크롤되면 안 되는 것은 `SGnb` 의 위아래 고정 슬롯에 둔다.** 레일과 메뉴에 각각 위(`railTop`·`menuTop`)와 아래(`railFooter`·`menuFooter`) 슬롯이 있다. 아이템이 많아 넘치면 **목록만 스크롤되고 이 슬롯들은 제자리에 남는다** — 메뉴 검색, 워크스페이스 전환, 계정 행처럼 항상 보여야 하는 것이 여기 온다. 레일 슬롯은 `showRail` 일 때만, 메뉴 슬롯은 깔 메뉴가 있을 때만 렌더된다.
 
 **접으면 레일·메뉴가 통째로 빠져나가면서 그 슬롯들도 함께 사라진다.** 접힌 상태에서도 남겨야 할 것은 `foldedTop`·`foldedFooter` 로 따로 준다 — `header="fix"` 로 접혔을 때만 나타나며, 폭이 좁은 폴드 레일이므로 아이콘 버튼 하나 정도로 줄인다.
 
 ```tsx
 {/* 접히면 menuTop·menuFooter 가 함께 빠지므로, 폴드 레일에 남길 것만 foldedTop 으로 따로 준다 */}
 <SGnb
-  items={MENU} value={current} onValueChange={navigate} useRail
+  items={MENU} value={current} onValueChange={navigate} showRail
   menuTop={<SSearchInput value={keyword} onValueChange={setKeyword} placeholder="메뉴 검색" />}
   menuFooter={<AccountRow />}
   foldedTop={<SGhostButton icon="search" size="sm" ariaLabel="메뉴 검색" onClick={openSearch} />}
@@ -1793,7 +1813,7 @@ import { SModalOutlet } from 'sellmate-design-system-react';
   - **닫힘은 `onTooltipDismiss` 로 받아 `tooltip` 을 비워 둔다.** 같은 값을 계속 넘기는 동안에는 다시 뜨지 않고, **비웠다 다시 넘기면 문구가 같아도 새 안내로 뜬다** — 새 알림마다 같은 안내를 다시 띄우는 화면이 막히지 않는다.
   - 재노출 신호는 문구가 **없음 → 있음** 으로 바뀌는 것이다. 한 이벤트 핸들러 안에서 비웠다 곧바로 넣으면 렌더가 한 번으로 묶여 신호가 되지 않는다 — 닫을 때 비우고, 다시 필요할 때 넘긴다.
   - 컴포넌트가 아는 범위는 그 자리가 서 있는 동안뿐이다(새로고침하거나 GNB 를 접어 알림이 다른 자리로 옮겨 서면 새로 마운트된다). **그 사용자에게 두 번 다시 보이지 않아야 하면 앱이 닫힘을 저장해 두고 `tooltip` 을 넘기지 않는다.**
-- **`header="fix"` + `useRail` 에서 하위 메뉴가 없는 레일 아이템이 활성이면 메뉴 컬럼째 사라지므로 이 패널도 함께 빠진다.** 항상 보여야 하는 계정·알림이라면 그런 레일 리프를 두지 않는다 — 또는 `header="full"` 로 두면 상단바에 남는다(그런 레일 리프가 있으면 GNB 가 `header` 를 `full` 로 강제한다).
+- **`header="fix"` + `showRail` 에서 하위 메뉴가 없는 레일 아이템이 활성이면 메뉴 컬럼째 사라지므로 이 패널도 함께 빠진다.** 항상 보여야 하는 계정·알림이라면 그런 레일 리프를 두지 않는다 — 또는 `header="full"` 로 두면 상단바에 남는다(그런 레일 리프가 있으면 GNB 가 `header` 를 `full` 로 강제한다).
 
 ### 4-2. 목록 페이지 (필터 + 테이블)
 
@@ -1821,7 +1841,7 @@ import {
 const filterFields: SKeyValueField[][] = [
   [
     { name: 'status', label: '상태', type: 'select',
-      options: { options: STATUS_OPTIONS, emitValue: true } },
+      options: { options: STATUS_OPTIONS, valueAsPrimitive: true } },
     { name: 'keyword', label: '검색어', type: 'input',
       options: { placeholder: '상품명 / 상품코드' } },
   ],
@@ -1853,6 +1873,7 @@ export default function ProductListPage() {
   return (
     <AppShell
       header={{
+        variant: 'bar',
         title: '상품 목록',
         // 이 페이지의 주요 액션이 아니라 부가 액션 — slot 은 sm 버튼으로만 채운다
         slot: <SButton size="sm" color="neutral" outline label="이용 가이드" onClick={openGuide} />,
@@ -1895,7 +1916,7 @@ export default function ProductListPage() {
           selected={selected}
           onSelectedChange={setSelected}
           pagination={{ currentPage, lastPage }}
-          isLoading={isLoading}
+          loading={loading}
         />
       </div>
     </AppShell>
@@ -1911,7 +1932,7 @@ export default function ProductListPage() {
 
 ```tsx
 // 좁게 시작하고, 사용자가 바꾸는 밀도는 표가 알아서 들고 간다
-<STable dense useRowsPerPageSelect pagination={{ currentPage, lastPage }} />;
+<STable dense showRowsPerPageSelect pagination={{ currentPage, lastPage }} />;
 
 // 사용자가 고른 밀도를 다음 방문에도 남기려는 화면만 받아서 저장한다.
 // 저장한 값은 시작 밀도로만 돌려준다 — 되돌려 넣지 않는다
@@ -1920,7 +1941,7 @@ const [initialDense] = useState(() => loadPref('list.dense', true));
 <STable
   dense={initialDense}
   onDenseChange={next => savePref('list.dense', next)}
-  useRowsPerPageSelect
+  showRowsPerPageSelect
   pagination={{ currentPage, lastPage }}
 />;
 ```
@@ -1968,7 +1989,7 @@ const fields: SKeyValueField[][] = [
   ],
   [
     { name: 'category', label: '카테고리', required: true, type: 'select',
-      options: { options: CATEGORY_OPTIONS, emitValue: true,
+      options: { options: CATEGORY_OPTIONS, valueAsPrimitive: true,
         rules: [required('카테고리를 선택해 주세요.')] } },
     { name: 'price', label: '판매가', type: 'number-input' },
   ],
@@ -1983,9 +2004,9 @@ export default function ProductCreatePage() {
   const [values, setValues] = useState<Record<string, unknown>>({});
 
   return (
-    <AppShell header={{ title: '상품 등록', onBack: goBack }}>
+    <AppShell header={{ variant: 'bar', title: '상품 등록', onBack: goBack }}>
       <div className="flex flex-col gap-sd-12">
-        <SForm ref={formRef} formClass="flex flex-col gap-sd-12" onSubmit={save}>
+        <SForm ref={formRef} formClassName="flex flex-col gap-sd-12" onSubmit={save}>
           <SKeyValueTable
             fields={fields}
             values={values}
@@ -2046,7 +2067,7 @@ const priceFields: SKeyValueField[][] = [
 export default function ProductDetailPage() {
   return (
     // 목록에서 들어온 상세 페이지 — onBack 으로 뒤로가기를 준다
-    <AppShell header={{ fix: true, title: '클래식 셔츠', onBack: goList }}>
+    <AppShell header={{ variant: 'bar', title: '클래식 셔츠', onBack: goList }}>
       <div className="flex flex-col gap-sd-12">
         <SSectionHeaderCard title="기본 정보" marker thickness="accent">
           <SKeyValueTable fields={basicFields} values={product} />

package/dist/styles.css

@@ -768,6 +768,9 @@
   .mx-\[calc\(12px-var\(--cmp-chipFilter-chip-group\)\)\] {
     margin-inline: calc(12px - var(--cmp-chipFilter-chip-group));
   }
+  .mx-auto {
+    margin-inline: auto;
+  }
   .my-\[4px\] {
     margin-block: 4px;
   }
@@ -1055,6 +1058,9 @@
   .h-\[250px\] {
     height: 250px;
   }
+  .h-\[260px\] {
+    height: 260px;
+  }
   .h-\[280px\] {
     height: 280px;
   }
@@ -1277,6 +1283,9 @@
   .w-\[61px\] {
     width: 61px;
   }
+  .w-\[72px\] {
+    width: 72px;
+  }
   .w-\[176px\] {
     width: 176px;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sellmate-design-system-react",
-  "version": "9.0.0-beta.40",
+  "version": "9.0.0-beta.41",
   "description": "Sellmate Design System — React (TypeScript + Tailwind v4) port",
   "license": "UNLICENSED",
   "keywords": [