sellmate-design-system-react 9.0.0-beta.62 → 9.0.0-beta.64

package/AGENTS.md

@@ -308,6 +308,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 | 상황 | 값 |
 | --- | --- |
 | **페이지 콘텐츠 패딩** | **`SPage` 가 `--cmp-pageBody-padding-default` 로 이미 넣는다.** 직접 주지 않는다 (덮어쓰면 토큰이 바뀌어도 안 따라간다). `SPage` 밖에서 같은 패딩이 필요하면 `p-sd-16` |
+| **가장자리까지 차는 블록이 맨 위에 서는 페이지** (`SChipFilter` 바 등) | `SPage` 에 `padding="none"` 으로 끄고, **그 아래 블록이 `p-[var(--cmp-pageBody-padding-default)]` 로 같은 토큰의 여백을 잡는다.** `className="p-0"` 이나 `p-sd-16` 으로 적지 않는다 (§4-2 칩 필터) |
 | **섹션 ↔ 섹션**, **블록 ↔ 블록** (헤더·필터·본문 사이) | **`gap-sd-12`** |
 | **툴바 ↔ 그 표** (`STableBar` ↔ `STable`) | **간격 없음 — 붙인다.** 둘은 한 블록이다 (§2-0) |
 | 요소 ↔ 요소 | **기본 `gap-sd-8`** (`--sys-space-stack-gap-element-normal`) · 타이트 `gap-sd-4`(`-tight`) · 여유 `gap-sd-12`(`-relaxed`) / `gap-sd-16`(`-wide`) |
@@ -407,7 +408,7 @@ Tailwind 유틸리티는 **토큰 스케일에 있는 값만** 사용한다.
 ```
 
 - **`bordered={false}`** 로 표의 테두리를 끈다. 카드가 이미 그린다.
-- **`radius="useTop"`** 으로 위쪽 모서리를 죽인다. 아래쪽 라운드는 카드가 처리한다.
+- **`radius="useTop"`** 으로 위쪽 모서리를 죽인다. 아래쪽 라운드는 카드가 처리한다. **표 아래에 카드 푸터(`button`·`footerLeft`)가 오면 `radius="full"`** — 아래 모서리도 카드가 아니라 푸터의 상단 구분선이 이어받으므로 네 모서리를 모두 죽인다.
 - `STable` 은 **페이지네이션 바의 테두리와 `-mt-px` 겹침도 함께 꺼진다** — 본문 테두리가 없으면 겹칠 대상이 없어, 그대로 두면 페이지네이션만 테두리를 갖고 1px 어긋난다.
 
 #### 본문 바탕 눌러앉히기 (선택)
@@ -1352,6 +1353,7 @@ tableRef.current.scrollToRow(row);                  // 복원
 - **왼쪽 끝**: 취소·닫기·목록 등 되돌리는 액션
 - **오른쪽 끝**: 저장·등록·수정·삭제 등 실행 액션
 - 체크박스·안내 문구 등 **부가 요소는 오른쪽 그룹 안, 실행 버튼 바로 왼쪽**에 둔다
+- **되돌리는 액션이 없어도 양끝 분리는 그대로다** — 오른쪽에 모으지 않는다. 그때는 **위계가 낮은 실행 액션이 왼쪽 끝, 가장 강한 실행 액션이 오른쪽 끝**이다. 뒤로가기를 헤더의 `onBack` 이 맡은 상세 페이지(§4-4)의 `삭제`(`danger outline`) · `수정`(`primary` 채움)이 이 경우다.
 
 ```tsx
 <div className="flex items-center justify-between">
@@ -1699,17 +1701,18 @@ useEffect(() => {
 | 연도+월 선택 리스트만 필요하다 (트리거·팝오버는 직접 조합) | `SDatePickerMonthListbox` |
 | **시작~종료** 를 값으로 받는다 | `SDateRangePicker` |
 | 달력 격자 **자체가 화면 콘텐츠** 다 (날짜를 고르게 한다) | `SCalendar` |
-| 한 달치 **일정을 읽게** 펼친다 (칸마다 여러 건) | `SCalendarBoard` |
+| 한 달치 **일정을 읽게** 펼친다 (칸마다 여러 건, 여러 날에 걸친 일정 포함) | `SCalendarBoard` |
 
 - **기간을 `SDatePicker` 두 개로 만들지 않는다.** 시작이 종료보다 뒤인 입력을 막는 검증과 한쪽만 고른 중간 상태 처리가 `SDateRangePicker` 안에 이미 있다. 두 개로 쪼개면 그게 전부 앱 몫이 된다.
 - `SDatePicker`·`SDateRangePicker` 는 내부적으로 `SCalendar` 를 팝오버로 띄운다. 값을 받는 자리에 `SCalendar` 를 직접 쓰지 않는다.
 - **`SCalendar` 와 `SCalendarBoard` 는 방향이 반대다.** `SCalendar` 는 날짜를 **고르는** 달력(칸에는 점만 찍힌다)이고, `SCalendarBoard` 는 일정을 **읽는** 달력이다 — 칸마다 일정이 줄로 쌓이고, 칸 높이에 담기는 줄 수를 넘으면 "N개 더보기" 로 접히고, **"더보기" 또는 일정이 있는 칸 아무 데나** 누르면 **그 칸을 덮으며 뜨는 판**에 그 날짜의 일정이 전부 펼쳐진다. 폭도 다르다: `SCalendar` 는 제 폭을 갖는 요소, `SCalendarBoard` 는 페이지 폭을 채우는 블록이다.
 - **`SCalendarBoard` 는 기본이 읽기 전용 판이다.** 날짜 칸을 눌러 **고르게** 하려면 `selectable` 을 켠다 — 켜야 `onValueChange(date, events)` 로 고른 날짜와 **그 날짜의 일정**이 함께 온다. 다만 **일정이 있는 칸은 `selectable` 과 무관하게 눌린다** — 그때는 목록 판이 열린다. 둘 다 켜져 있으면 고르기와 열기가 함께 일어난다. 일정 버튼과 "N개 더보기" 도 항상 눌린다.
+- **여러 날에 걸친 일정은 `events[].endDate` 로 준다.** 그날까지(그날 포함) **칸 경계를 넘어 하나의 막대로** 이어져 그려진다. 같은 일정을 날짜 수만큼 쪼개 넣지 않는다 — 쪼개면 칸마다 막대가 끊겨 보이고, 목록 판과 `onValueChange` 에도 건수가 부풀려 나간다. 줄은 **주 단위**로 정해져서, 막대가 지나가는 칸은 그 줄을 비워 두므로 다른 일정과 겹치지 않는다. 주 경계에서는 줄이 바뀌므로 조각이 나뉘고 **잘린 쪽 모서리가 평평해진다** — 앞/뒤로 이어진다는 표시다. **막대가 걸친 날은 모두 그 일정을 가진 날이다** — 어느 칸을 눌러도 목록 판에 함께 나오고 `onValueChange` 에도 실려 온다. `endDate` 가 `date` 보다 앞서면 하루짜리로 본다.
 - **칸 배경과 일정 색은 다른 층이다.** 그날의 성격(마감·완료·휴무 등)은 `dayColors` 로 **칸 전체**에 칠하고(`default` `danger` `accent` `complete` `dim`), 일정 하나의 색은 `events[].color` 로 준다. 둘을 섞어 쓰면 서로를 가리지 않고 함께 읽힌다.
 - 일정 왼쪽의 색 점은 `SBadge` 다 — `events[].color` 프리셋이 점 색까지 정하고, 따로 주려면 `dotColor` 에 `SBadge` 색(`SBadgeColor`) 중 하나를 넣는다 (§3-1).
 - **칸 본문을 통째로 바꾸려면 `dayContent` 다.** 일정으로 표현되지 않는 그날치 요약(재고·매출 같은)을 칸에 얹을 때 쓴다. **슬롯을 준 날짜는 그 날짜의 `events` 를 그리지 않고 목록 판도 열지 않는다** — 한 칸에 둘을 겹쳐 담지 않는다. 일정과 요약을 함께 보여야 하면 요약을 일정 한 건(`events[]`)으로 넣는다.
 - **`SCalendarBoard` 는 높이를 부모에게서 받는다.** 행이 그 높이를 균등하게 나눠 갖고, 칸 높이가 다시 "한 칸에 몇 줄이 보일지" 를 정한다. 그래서 **놓는 자리에 높이를 준다** — 페이지 본문의 남은 높이를 채우려면 `SPage` 안에서 스택을 `flex-1 min-h-0` 으로 두고 판에 `h-full` 을 준다. 높이를 주지 않으면 칸이 최소 높이로 주저앉아 한두 줄만 보인다.
-- **한 칸에 몇 줄을 펼칠지는 컴포넌트가 잰다.** 조절하는 prop 이 없다 — 칸 높이에서 나오는 값이라 따로 정할 것이 아니다. 줄이 넘치면 마지막 한 줄을 "N개 더보기" 에 내주므로 **접히든 아니든 칸 높이가 같다.** **소비 앱이 `events` 를 미리 잘라 넘기지 않는다.** 잘라 넘기면 "N개 더보기" 의 수가 실제 건수와 어긋나고, 눌러도 나머지가 나오지 않는다.
+- **한 칸에 몇 줄을 펼칠지는 컴포넌트가 잰다.** 조절하는 prop 이 없다 — 칸 높이에서 나오는 값이라 따로 정할 것이 아니다. 줄이 넘치면 마지막 한 줄을 "N개 더보기" 에 내주므로 **접히든 아니든 칸 높이가 같다.** 기간 막대가 접히면 **걸친 날마다 한 건으로** 세므로 날짜별 "N개" 가 서로 다를 수 있다. **소비 앱이 `events` 를 미리 잘라 넘기지 않는다.** 잘라 넘기면 "N개 더보기" 의 수가 실제 건수와 어긋나고, 눌러도 나머지가 나오지 않는다.
 - **`events[].label` 은 필수다** — 일정이 무엇인지 알리는 부분이라 비워 두지 않는다. 인라인 HTML 을 받으므로 부분 강조가 필요할 때만 태그를 쓰고, 나머지는 `description`·`value` 로 나눠 담는다. 칸이 좁아지면 `label`+`description` 이 한 덩어리로 말줄임되고 `value` 만 끝에 온전히 남는다 — **금액·수량은 반드시 `value` 에 담는다.** `description` 에 넣으면 잘린다.
 - `SDatePickerYearListbox`·`SDatePickerMonthListbox` 는 `SDatePicker` 의 mode listbox 조각만 떼어낸 컴포넌트다. 일반 폼 입력에는 `SDatePicker mode="year" | "month"` 를 우선 쓰고, 다른 트리거·팝오버 안에 리스트만 끼워 넣을 때만 직접 쓴다.
 
@@ -1952,6 +1955,8 @@ const [selectedId, setSelectedId] = useState<string>();
 >
 > **아래 레시피는 §2-0 조합 문법으로 유도된 결과다.** 여기 없는 화면(대시보드·설정·마법사 등)을 만들 때는 임의로 짜지 말고 §2-0 의 층 구조·포함 규칙·블록 순서로 직접 유도한다.
 >
+> **레시피 코드의 `./AppShell` 은 §4-1 의 셸, `./api`·`./router` 는 앱의 데이터 계층·라우터 자리다.** 각 레시피는 Storybook `Recipes/…` 에서 실제로 띄워 볼 수 있고, 아래에 적힌 분기(칩 필터·섹션 나눔 등)의 변형 코드도 거기 있다.
+>
 > **핵심 원칙 — 표 형태의 정보는 `SKeyValueTable` 로 만든다.** 필터·등록/수정 폼·상세 정보가 모두 여기 해당한다.
 > `SField` 컨트롤을 `div` 로 직접 나열해 폼을 만들지 않는다.
 > (필터만 예외가 하나 있다 — 조건 후보가 많아 골라 붙이게 해야 하면 `SChipFilter` 다. §3-7-11)
@@ -1959,7 +1964,11 @@ const [selectedId, setSelectedId] = useState<string>();
 ### 4-1. 앱 셸 (모든 페이지 공통)
 
 ```tsx
-import { SLayout, SGnb, SPage, SPageHeader, type SGnbMenuItem, type SPageHeaderProps } from 'sellmate-design-system-react';
+import type { ReactNode } from 'react';
+import {
+  SLayout, SGnb, SPage, SPageHeader,
+  type SGnbMenuItem, type SPageHeaderProps, type SPageContentHeight, type SPageContentWidth, type SPagePadding,
+} from 'sellmate-design-system-react';
 
 const MENU: SGnbMenuItem[] = [
   { label: '주문', value: 'orders', icon: 'bill' },
@@ -1971,12 +1980,15 @@ export default function AppShell({
   header,
   scrollEndSpacing,
   contentHeight,
+  contentWidth,
+  padding,
 }: {
-  children: React.ReactNode;
+  children: ReactNode;
   header?: SPageHeaderProps;
   scrollEndSpacing?: boolean;
   contentHeight?: SPageContentHeight;
   contentWidth?: SPageContentWidth;
+  padding?: SPagePadding;
 }) {
   return (
     <SLayout type="box" header="fix">
@@ -1985,7 +1997,8 @@ export default function AppShell({
       {/* 페이지 제목은 SPage 앞에 형제로 둔다 — SLayout 이 헤더부터 뒤를 한 열로 묶는다.
           header 는 페이지마다 달라 AppShell 이 그대로 받아 넘긴다 — 여기서 만들지 않는다 */}
       {header && <SPageHeader {...header} />}
-      {/* 콘텐츠 패딩은 SPage 가 토큰으로 넣는다 — p-sd-* 로 덮어쓰지 않는다 */}
+      {/* 콘텐츠 패딩은 SPage 가 토큰으로 넣는다 — p-sd-* 로 덮어쓰지 않는다.
+          가장자리까지 차는 블록이 맨 위에 서는 페이지만 padding="none" 으로 끈다 (§4-2 칩 필터) */}
       {/* 높이 모드는 페이지가 정한다 — 대부분 contentHeight="fill" 이다 (§2-2) */}
       {/* 스크롤 끝 여백도 SPage 가 넣는다. 페이지가 실제로 스크롤되는 화면에서만 켠다 */}
       {/* 가로 폭 모드도 페이지가 정한다 — 넓은 창에서 본문을 늘릴지 최소 폭으로 세울지 */}
@@ -1994,6 +2007,7 @@ export default function AppShell({
         scrollEndSpacing={scrollEndSpacing}
         contentHeight={contentHeight}
         contentWidth={contentWidth}
+        padding={padding}
       >
         {children}
       </SPage>
@@ -2199,7 +2213,7 @@ import { SModalOutlet } from 'sellmate-design-system-react';
 
 **뒤의 둘은 한 블록이라 붙여 쓴다** — 툴바는 자기 아래 표의 건수와 액션을 말하므로 사이를 벌리지 않는다. 묶는 방법과 맞닿는 변 처리는 §2-0 에 있다.
 
-필터 자리는 `SChipFilter` 로 바꿔 놓을 수 있다 — 조건 후보가 많아 쓸 것만 골라 붙이게 하는 화면이면 그쪽이다 (§3-7-11). 나머지 골격은 같다.
+필터 자리는 `SChipFilter` 로 바꿔 놓을 수 있다 — 조건 후보가 많아 쓸 것만 골라 붙이게 하는 화면이면 그쪽이다 (§3-7-11). 나머지 골격은 같지만 여백이 다르다 — **칩 필터 바는 페이지 가장자리까지 찬다.** `SPage` 에 `padding="none"` 을 주고(§4-1 의 셸이 넘긴다), 바에 `className="border-b"` 로 아래를 긋고(흰 바탕이라 흰 페이지 위에서 경계가 없다 — 선 색은 바가 토큰으로 들고 있어 두께만 준다), 그 아래 툴바+표 블록이 `p-[var(--cmp-pageBody-padding-default)]` 로 같은 토큰의 여백을 잡는다. 코드는 Storybook `Recipes/목록 페이지` 의 "칩 필터" 에 있다.
 
 액션 버튼의 위치가 핵심이다:
 
@@ -2211,44 +2225,120 @@ import { SModalOutlet } from 'sellmate-design-system-react';
   - `fill` 에서는 페이지가 스크롤하지 않으므로 **`scrollEndSpacing` 은 무시된다** — 따로 끄지 않는다 (§2-2).
 - **정렬 가능한 컬럼은 `sortable` 로 준다.** 정렬 상태(`sort`)는 이 페이지가 들고 `onSortChange` 로 받는다 — 조회 조건이라 URL 에 실려야 한다 (§3-4).
 
+<!-- recipe:src/recipes/ProductListPage.tsx — 아래 코드 블록은 이 파일에서 생성된다(scripts/gen-recipes.mjs). 여기를 고치지 말고 파일을 고친다 -->
 ```tsx
+import { useState } from 'react';
 import {
-  SButton, SKeyValueTable, STableBar, STable, STag,
-  type STableColumn, type SRow, type SKeyValueField,
+  SButton,
+  SKeyValueTable,
+  STable,
+  STableBar,
+  STag,
+  type SDateRangeValue,
+  type SKeyValueField,
+  type SRow,
+  type STableColumn,
+  type STableSort,
 } from 'sellmate-design-system-react';
+import AppShell from './AppShell';
+import { STATUS_OPTIONS, removeProducts, useProductList, type ProductQuery } from './api';
+import { useNavigate } from './router';
 
 /** 필터도 표다 — SKeyValueTable 로 만든다 (서비스 전용 전역 필터가 따로 있는 경우 제외) */
 const filterFields: SKeyValueField[][] = [
   [
-    { name: 'status', label: '상태', type: 'select',
-      options: { options: STATUS_OPTIONS, valueAsPrimitive: true } },
-    { name: 'keyword', label: '검색어', type: 'input',
-      options: { placeholder: '상품명 / 상품코드' } },
+    // 조회 조건으로 쓰는 셀렉트·날짜 피커는 clearable — 걸어 둔 조건을 풀 수 있어야 한다 (§3-7-4)
+    {
+      name: 'status',
+      label: '상태',
+      type: 'select',
+      options: { options: STATUS_OPTIONS, valueAsPrimitive: true, clearable: true },
+    },
+    {
+      name: 'keyword',
+      label: '검색어',
+      type: 'input',
+      options: { placeholder: '상품명 / 상품코드' },
+    },
   ],
   [
-    { name: 'period', label: '등록일', type: 'date-range-picker', tdColSpan: 3 },
+    {
+      name: 'period',
+      label: '등록일',
+      type: 'date-range-picker',
+      tdColSpan: 3,
+      options: { clearable: true },
+    },
   ],
 ];
 
+// 정렬·폭은 값의 성격에서 나온다 (§3-4). 모든 컬럼에 폭을 px 로 명시한다
 const columns: STableColumn[] = [
-  // 숫자 컬럼은 전부 align: 'right' — §3-4
-  { name: 'id', label: 'ID', field: 'id', width: '80px', align: 'right' },
-  { name: 'name', label: '상품명', field: 'name' },
-  { name: 'stock', label: '재고', field: 'stock', width: '90px', align: 'right',
-    format: (v: number) => `${Number(v).toLocaleString()}개` },
-  { name: 'price', label: '판매가', field: 'price', width: '120px', align: 'right',
-    format: (v: number) => `${Number(v).toLocaleString()}원` },
-  // 상태 컬럼은 STag size="sm" — SBadge 색 점을 기본으로 쓰지 않는다
-  { name: 'status', label: '상태', field: 'status', width: '100px', align: 'center',
+  // ID·코드는 크기를 비교하는 숫자가 아니라 식별자다 → center. right 는 양을 나타내는 값에만
+  { name: 'id', label: 'ID', field: 'id', width: 80, align: 'center' },
+  // 자유 입력 텍스트 → 기준 폭을 주고, 표에 resizable 을 켜서 사용자가 늘릴 수 있게 한다
+  { name: 'name', label: '상품명', field: 'name', width: 240 },
+  // 값의 크기를 비교하는 컬럼만 sortable — 정렬 상태는 페이지가 들고 있다
+  {
+    name: 'stock',
+    label: '재고',
+    field: 'stock',
+    width: 100,
+    align: 'right',
+    sortable: true,
+    format: (v: unknown) => `${Number(v).toLocaleString()}개`,
+  },
+  {
+    name: 'price',
+    label: '판매가',
+    field: 'price',
+    width: 120,
+    align: 'right',
+    sortable: true,
+    format: (v: unknown) => `${Number(v).toLocaleString()}원`,
+  },
+  // 상태 컬럼은 STag size="sm" — SBadge 색 점을 기본으로 쓰지 않는다.
+  // 컨트롤이 들어가는 컬럼은 contentType: 'control', resizable 표에서는 minWidth 도 함께 (§3-4)
+  {
+    name: 'status',
+    label: '상태',
+    field: 'status',
+    width: 100,
+    minWidth: 100,
+    align: 'center',
+    contentType: 'control',
     render: (row: SRow) =>
-      row.status === 'selling'
-        ? <STag size="sm" color="green" label="판매중" />
-        : <STag size="sm" color="grey" label="판매중지" /> },
+      row.status === 'selling' ? (
+        <STag size="sm" color="green" label="판매중" />
+      ) : (
+        <STag size="sm" color="grey" label="판매중지" />
+      ),
+  },
 ];
 
 export default function ProductListPage() {
+  const navigate = useNavigate();
+  // 편집 중인 필터 값과, 검색을 눌러 실제로 걸린 조회 조건은 따로 든다.
+  // 조회 조건(필터·정렬·페이지)은 실제 앱에서는 URL 쿼리에 싣는다 — 새로고침·공유에 살아남아야 한다
   const [filters, setFilters] = useState<Record<string, unknown>>({});
+  const [query, setQuery] = useState<ProductQuery>({ page: 1, rowsPerPage: 20 });
   const [selected, setSelected] = useState<SRow[]>([]);
+  const { rows, total, lastPage, loading } = useProductList(query);
+
+  const search = () => {
+    setQuery(q => ({
+      ...q,
+      status: (filters.status as string | null) ?? undefined,
+      keywords: filters.keyword ? [String(filters.keyword)] : undefined,
+      period: (filters.period as SDateRangeValue) ?? undefined,
+      page: 1,
+    }));
+  };
+
+  const removeSelected = async () => {
+    await removeProducts(selected.map(row => Number(row.id)));
+    setSelected([]);
+  };
 
   return (
     <AppShell
@@ -2256,7 +2346,15 @@ export default function ProductListPage() {
         variant: 'bar',
         title: '상품 목록',
         // 이 페이지의 주요 액션이 아니라 부가 액션 — slot 은 sm 버튼으로만 채운다
-        slot: <SButton size="sm" color="neutral" outline label="이용 가이드" onClick={openGuide} />,
+        slot: (
+          <SButton
+            size="sm"
+            color="neutral"
+            outline
+            label="이용 가이드"
+            onClick={() => navigate('/guide/products')}
+          />
+        ),
       }}
       contentHeight="fill" // 표가 남은 높이를 채우고 페이지네이션이 하단에 고정된다
     >
@@ -2270,10 +2368,11 @@ export default function ProductListPage() {
           fieldWidth="fill"
           search
           onChange={({ values }) => setFilters(values)}
-          onSearch={fetchList}
+          onSearch={search}
         />
 
-        {/* 툴바+표 = 한 블록. 사이를 벌리지 않는다 (§2-0) */}
+        {/* 툴바+표 = 한 블록. 사이를 벌리지 않는다 (§2-0).
+            이 div 도 높이 사슬의 한 칸이라 min-h-0 flex-1 이 필요하다 */}
         <div className="flex min-h-0 flex-1 flex-col">
           {/* 툴바 — 좌: 건수 + (구분선 자동) + 선택 액션 / 우: 주요 액션
               맞닿는 가로선은 표가 그리므로 아래 테두리는 지운다 */}
@@ -2283,25 +2382,37 @@ export default function ProductListPage() {
             selected={selected.length}
             actions={
               /* 선택 항목 단위 파괴 액션 → danger outline (§3-5-3) */
-              <SButton size="sm" color="danger" outline label="선택 삭제"
-                disabled={!selected.length} onClick={removeSelected} />
+              <SButton
+                size="sm"
+                color="danger"
+                outline
+                label="선택 삭제"
+                disabled={!selected.length}
+                onClick={removeSelected}
+              />
             }
             rightActions={
               /* 이 페이지의 유일한 primary 채움 (§3-5-1) */
-              <SButton size="sm" label="상품 등록" onClick={goCreate} />
+              <SButton size="sm" label="상품 등록" onClick={() => navigate('/products/new')} />
             }
           />
 
-          {/* 남은 높이를 채우고 본문만 스크롤한다 — 페이지네이션 바는 표 안에서 하단 고정 */}
+          {/* 남은 높이를 채우고 본문만 스크롤한다 — 페이지네이션 바는 표 안에서 하단 고정.
+              dense 는 시작 밀도이자 밀도 토글의 스위치 — onDenseChange 값을 되돌려 넣지 않는다 (§4-2) */}
           <STable
             className="min-h-0 flex-1"
             columns={columns}
             rows={rows}
             rowKey="id"
+            dense
+            resizable
             selectable
             selected={selected}
             onSelectedChange={setSelected}
-            pagination={{ currentPage, lastPage }}
+            sort={query.sort}
+            onSortChange={(sort: STableSort | null) => setQuery(q => ({ ...q, sort, page: 1 }))}
+            pagination={{ page: query.page, rowsPerPage: query.rowsPerPage, lastPage }}
+            onPageChange={page => setQuery(q => ({ ...q, page }))}
             loading={loading}
           />
         </div>
@@ -2310,6 +2421,7 @@ export default function ProductListPage() {
   );
 }
 ```
+<!-- /recipe -->
 
 #### 한 화면에 더 많은 행을 — `dense` 와 밀도 토글
 
@@ -2319,7 +2431,7 @@ export default function ProductListPage() {
 
 ```tsx
 // 좁게 시작하고, 사용자가 바꾸는 밀도는 표가 알아서 들고 간다
-<STable dense showRowsPerPageSelect pagination={{ currentPage, lastPage }} />;
+<STable dense showRowsPerPageSelect pagination={{ page, rowsPerPage, lastPage }} />;
 
 // 사용자가 고른 밀도를 다음 방문에도 남기려는 화면만 받아서 저장한다.
 // 저장한 값은 시작 밀도로만 돌려준다 — 되돌려 넣지 않는다
@@ -2329,7 +2441,7 @@ const [initialDense] = useState(() => loadPref('list.dense', true));
   dense={initialDense}
   onDenseChange={next => savePref('list.dense', next)}
   showRowsPerPageSelect
-  pagination={{ currentPage, lastPage }}
+  pagination={{ page, rowsPerPage, lastPage }}
 />;
 ```
 
@@ -2394,61 +2506,113 @@ const [initialDense] = useState(() => loadPref('list.dense', true));
 
 **병합으로 찬 자리는 배열 순서가 아니라 실제 열 위치로 판정한다.** 그러니 아래 행의 필드를 병합된 열에 맞추려고 자리 채우기용 빈 필드를 끼우지 않는다 — 앞 필드에 `tdColSpan` 이나 `hideTh` 가 있어도 남은 필드가 알아서 빈 열부터 놓인다.
 
+<!-- recipe:src/recipes/ProductCreatePage.tsx — 아래 코드 블록은 이 파일에서 생성된다(scripts/gen-recipes.mjs). 여기를 고치지 말고 파일을 고친다 -->
 ```tsx
+import { useState } from 'react';
 import {
-  SForm, SKeyValueTable, SButton, SCheckbox,
-  type SFormHandle, type SKeyValueField, type Rule,
+  SButton,
+  SCheckbox,
+  SForm,
+  SKeyValueTable,
+  type Rule,
+  type SKeyValueField,
 } from 'sellmate-design-system-react';
+import AppShell from './AppShell';
+import { CATEGORY_OPTIONS, saveProduct } from './api';
+import { useNavigate } from './router';
 
-const required = (msg: string): Rule => v =>
-  v != null && String(v).trim() !== '' ? true : msg;
+const required =
+  (msg: string): Rule =>
+  v =>
+    v != null && String(v).trim() !== '' ? true : msg;
 
+/** 필드를 div 로 나열하지 않는다 — SKeyValueTable 의 행으로 구성한다 */
 const fields: SKeyValueField[][] = [
   [
-    { name: 'name', label: '상품명', required: true, type: 'input',
-      options: { placeholder: '상품명 입력', rules: [required('상품명을 입력해 주세요.')] } },
+    {
+      name: 'name',
+      label: '상품명',
+      required: true,
+      type: 'input',
+      options: { placeholder: '상품명 입력', rules: [required('상품명을 입력해 주세요.')] },
+    },
     { name: 'code', label: '상품코드', type: 'input', options: { placeholder: '자동 생성' } },
   ],
   [
-    { name: 'category', label: '카테고리', required: true, type: 'select',
-      options: { options: CATEGORY_OPTIONS, valueAsPrimitive: true,
-        rules: [required('카테고리를 선택해 주세요.')] } },
+    {
+      name: 'category',
+      label: '카테고리',
+      required: true,
+      type: 'select',
+      options: {
+        options: CATEGORY_OPTIONS,
+        valueAsPrimitive: true,
+        rules: [required('카테고리를 선택해 주세요.')],
+      },
+    },
     { name: 'price', label: '판매가', type: 'number-input' },
   ],
   [
-    { name: 'memo', label: '메모', type: 'textarea', tdColSpan: 3,
-      helpText: ['내부 관리용 메모입니다.'] },
+    // 가장 긴 행(필드 2개 = 4칸)에 맞춰 마지막 필드가 남는 칸을 채운다
+    {
+      name: 'memo',
+      label: '메모',
+      type: 'textarea',
+      tdColSpan: 3,
+      helpText: ['내부 관리용 메모입니다.'],
+    },
   ],
 ];
 
 export default function ProductCreatePage() {
-  const formRef = useRef<SFormHandle>(null);
+  const navigate = useNavigate();
   const [values, setValues] = useState<Record<string, unknown>>({});
+  const [keepOpen, setKeepOpen] = useState(false);
+
+  // SForm 이 하위 컨트롤의 rules 를 모아 submit 때 일괄 검증한다 — 통과했을 때만 불린다
+  const save = async () => {
+    await saveProduct(values);
+    if (keepOpen) setValues({});
+    else navigate('/products');
+  };
 
   return (
-    <AppShell header={{ variant: 'bar', title: '상품 등록', onBack: goBack }}>
-      <div className="flex flex-col gap-sd-12">
-        <SForm ref={formRef} formClassName="flex flex-col gap-sd-12" onSubmit={save}>
-          <SKeyValueTable
-            fields={fields}
-            values={values}
-            onChange={({ values }) => setValues(values)}
-          />
+    <AppShell
+      header={{ variant: 'bar', title: '상품 등록', onBack: () => navigate(-1) }}
+      contentHeight="fill" // 폼 페이지도 fill 이 기본 — 폼이 길어 실제로 스크롤될 때만 auto + scrollEndSpacing
+    >
+      <SForm formClassName="flex flex-col gap-sd-12" onSubmit={save}>
+        <SKeyValueTable
+          fields={fields}
+          values={values}
+          onChange={({ values }) => setValues(values)}
+        />
 
-          {/* 하단 버튼은 양끝으로 벌린다. 부가 요소(체크박스 등)는 저장 바로 왼쪽 */}
-          <div className="flex items-center justify-between">
-            <SButton type="button" color="neutral" outline label="취소" onClick={goBack} />
-            <div className="flex items-center gap-sd-8">
-              <SCheckbox label="계속 등록하기" value={keepOpen} onValueChange={v => setKeepOpen(v as boolean)} />
-              <SButton type="submit" label="저장" />
-            </div>
+        {/* 버튼 순서는 모든 화면에서 같다 — 취소는 왼쪽 끝, 저장은 오른쪽 끝.
+            부가 요소(체크박스 등)는 저장 바로 왼쪽 */}
+        <div className="flex items-center justify-between">
+          <SButton
+            type="button"
+            color="neutral"
+            outline
+            label="취소"
+            onClick={() => navigate(-1)}
+          />
+          <div className="flex items-center gap-sd-8">
+            <SCheckbox
+              label="계속 등록하기"
+              value={keepOpen}
+              onValueChange={v => setKeepOpen(v as boolean)}
+            />
+            <SButton type="submit" label="저장" />
           </div>
-        </SForm>
-      </div>
+        </div>
+      </SForm>
     </AppShell>
   );
 }
 ```
+<!-- /recipe -->
 
 ### 4-4. 상세(조회) 페이지
 
@@ -2456,7 +2620,7 @@ export default function ProductCreatePage() {
 
 - 조회 값은 `type: 'text'` 행으로 표시한다. **상태·분류 태그도 별도 영역이 아니라 표의 한 행**으로 넣는다 (`render` 에 `STag`).
 - 행이 많아지면 **유형별로 섹션을 나누고, 각 섹션을 `SSectionHeaderCard` 로 감싼다.**
-  섹션 제목은 `title` prop 으로, 바디 여백은 `padding` prop 으로 준다.
+  섹션 제목은 `title` prop 으로, 바디 여백은 `padding` prop 으로 준다. **카드 안이 `SKeyValueTable` 하나뿐이면 `padding="none"` 으로 가장자리까지 채우고 표는 `bordered={false} radius="useTop"`** 으로 자기 테두리를 끈다 (§2-2 "카드 가장자리까지 채우는 표").
 - **한 화면에 행이 많아 훑어보기가 목적이면 `SKeyValueTable` 에 `dense` 를 켠다** — 셀 상하 여백과
   최소 높이가 함께 내려가 행이 좁아진다. 다만 **읽기 전용(`text`) 행에서만 실제로 좁아진다**:
   폼 필드가 든 행은 필드 자체의 높이가 행 높이를 정하므로 거의 변하지 않는다. 그래서 필터(§4-2)나
@@ -2465,23 +2629,19 @@ export default function ProductCreatePage() {
 - **상세 페이지도 `contentHeight="fill"` 이 기본이다**(§2-2). 섹션이 많아 페이지가 실제로 스크롤되는 화면에서만 `auto` + `scrollEndSpacing` 을 켠다.
 - **섹션마다 독립 인라인 폼이 있는 형태**도 상세 페이지의 변형이다. 섹션 안에서 바로 수정·저장하게 하는 화면인데, 이때 버튼 강조는 **섹션 단위가 아니라 페이지 단위로 판단한다** — §3-5-1 의 "`secondary` 연속 배치 금지"는 섹션이 다르면 적용되지 않는다. 그 섹션 안에서 닫히는 저장·취소는 `SSectionHeaderCard` 의 `button`·`footerLeft` 로 넘긴다 (§3-7-8). 아래 예처럼 **페이지 전체를 확정하는 버튼은 카드 밖 하단 줄**에 둔다 — 둘을 섞지 않는다.
 
+<!-- recipe:src/recipes/ProductDetailPage.tsx — 아래 코드 블록은 이 파일에서 생성된다(scripts/gen-recipes.mjs). 여기를 고치지 말고 파일을 고친다 -->
 ```tsx
 import {
-  SSectionHeaderCard, SKeyValueTable, SButton, STag, type SKeyValueField,
+  SButton,
+  SKeyValueTable,
+  SModal,
+  SSectionHeaderCard,
+  STag,
+  type SKeyValueField,
 } from 'sellmate-design-system-react';
-
-const basicFields: SKeyValueField[][] = [
-  [
-    { name: 'code', label: '상품코드', type: 'text' },
-    { name: 'createdAt', label: '등록일', type: 'text' },
-  ],
-  [
-    { name: 'category', label: '카테고리', type: 'text' },
-    // 상태 태그도 표의 한 행으로 표현한다
-    { name: 'status', label: '상태',
-      render: <STag size="sm" color="green" label="판매중" /> },
-  ],
-];
+import AppShell from './AppShell';
+import { removeProducts, useProduct } from './api';
+import { useNavigate, useParams } from './router';
 
 const priceFields: SKeyValueField[][] = [
   [
@@ -2491,41 +2651,96 @@ const priceFields: SKeyValueField[][] = [
 ];
 
 export default function ProductDetailPage() {
+  const navigate = useNavigate();
+  const { id } = useParams();
+  const product = useProduct(Number(id));
+
+  // 되돌릴 수 없는 액션은 실행 여부만 확정받는다 — 직접 만든 confirm 대신 SModal.confirm (§3-3-1)
+  const confirmDelete = () =>
+    SModal.confirm({
+      type: 'negative',
+      modalTitle: '상품을 삭제할까요?',
+      topMessage: ['삭제된 상품은 복구할 수 없습니다.'],
+      mainButtonLabel: '삭제',
+    }).onOk(async () => {
+      await removeProducts([product.id]);
+      navigate('/products');
+    });
+
+  // 조회 값은 type: 'text' 행으로 보인다.
+  // 상태 태그도 별도 영역이 아니라 표의 한 행이다 — 값에 따라 달라지므로 컴포넌트 안에서 만든다
+  const basicFields: SKeyValueField[][] = [
+    [
+      { name: 'code', label: '상품코드', type: 'text' },
+      { name: 'createdAt', label: '등록일', type: 'text' },
+    ],
+    [
+      { name: 'category', label: '카테고리', type: 'text' },
+      {
+        name: 'status',
+        label: '상태',
+        render:
+          product.status === 'selling' ? (
+            <STag size="sm" color="green" label="판매중" />
+          ) : (
+            <STag size="sm" color="grey" label="판매중지" />
+          ),
+      },
+    ],
+  ];
+
   return (
     // 목록에서 들어온 상세 페이지 — onBack 으로 뒤로가기를 준다
-    <AppShell header={{ variant: 'bar', title: '클래식 셔츠', onBack: goList }}>
+    <AppShell
+      header={{ variant: 'bar', title: product.name, onBack: () => navigate('/products') }}
+      contentHeight="fill" // 섹션이 많아 실제로 스크롤될 때만 auto + scrollEndSpacing
+    >
       <div className="flex flex-col gap-sd-12">
-        <SSectionHeaderCard title="기본 정보" marker thickness="accent">
-          <SKeyValueTable fields={basicFields} values={product} />
+        {/* 행이 많아지면 유형별로 섹션을 나눈다. 카드가 둘 이상이라 marker 를 켠다 —
+            한 페이지 안의 카드 강조(marker·thickness)는 전부 같게 간다 (§4-5).
+            카드 안이 표 하나뿐이면 padding="none" 으로 가장자리까지 채우고, 표는 bordered={false} 로
+            자기 테두리를 끄고 radius="useTop" 으로 위 모서리를 죽인다 — 카드가 테두리·아래 라운드를 그린다 (§2-2) */}
+        <SSectionHeaderCard title="기본 정보" marker padding="none">
+          <SKeyValueTable fields={basicFields} values={product} bordered={false} radius="useTop" />
         </SSectionHeaderCard>
 
-        {/* 헤더 우측에 액션이 필요하면 slot 을 쓴다 */}
+        {/* 헤더 우측에 액션이 필요하면 slot 을 쓴다 — 이동 액션이라 outline (§3-5-1) */}
         <SSectionHeaderCard
           title="가격 정보"
           marker
           helpText={['부가세 포함 금액입니다.']}
-          slot={<SButton size="sm" color="secondary" label="이력" onClick={openHistory} />}
+          padding="none"
+          slot={
+            <SButton
+              size="sm"
+              color="neutral"
+              outline
+              label="이력"
+              onClick={() => navigate(`/products/${id}/price-history`)}
+            />
+          }
         >
-          <SKeyValueTable fields={priceFields} values={product} />
+          <SKeyValueTable fields={priceFields} values={product} bordered={false} radius="useTop" />
         </SSectionHeaderCard>
 
-        {/* 액션은 하단 — 목록(되돌리기)은 왼쪽 끝, 실행 액션은 오른쪽 끝 */}
+        {/* 액션은 하단 — 그룹을 모으지 않고 양끝으로 벌린다 (§3-5).
+            목록으로 돌아가기는 헤더의 onBack 이 이미 하므로 되돌리는 버튼을 따로 두지 않는다.
+            되돌리는 액션이 없어도 양끝 분리는 그대로다 — 위계가 낮은 삭제(danger outline)가 왼쪽 끝,
+            가장 강한 실행 액션인 수정이 오른쪽 끝 */}
         <div className="flex items-center justify-between">
-          <SButton color="neutral" outline label="목록" onClick={goList} />
-          <div className="flex items-center gap-sd-8">
-            <SButton color="danger" outline label="삭제" onClick={confirmDelete} />
-            <SButton label="수정" onClick={goEdit} />
-          </div>
+          <SButton color="danger" outline label="삭제" onClick={confirmDelete} />
+          <SButton label="수정" onClick={() => navigate(`/products/${id}/edit`)} />
         </div>
       </div>
     </AppShell>
   );
 }
 ```
+<!-- /recipe -->
 
 ### 4-5. 섹션 카드 — SSectionHeaderCard
 
-폼 페이지에서도 입력 항목이 많으면 유형별로 `SSectionHeaderCard` 로 나눈다. 주요 옵션:
+폼 페이지에서도 입력 항목이 많으면 유형별로 `SSectionHeaderCard` 로 나눈다. **카드 안이 `SKeyValueTable` 하나뿐이면 `padding="none"` 으로 가장자리까지 채우고, 표는 `bordered={false} radius="useTop"` 으로 자기 테두리를 끈다** (§2-2 "카드 가장자리까지 채우는 표"). 코드는 Storybook `Recipes/폼 페이지` 의 "섹션 나눔" 에 있다. 주요 옵션:
 
 | Prop (Header) | 용도 |
 | --- | --- |
@@ -2568,24 +2783,48 @@ export default function ProductDetailPage() {
 
 로그인 전이라 앱 셸이 아직 없다. `SLayout`·`SGnb`·`SPage` 가 없고, 회색 바탕 위에 카드 하나만 선다. (앱 셸 없이 서는 화면은 이것과 팝업 라우트(§4-7) 둘뿐이다.)
 
+<!-- recipe:src/recipes/LoginPage.tsx — 아래 코드 블록은 이 파일에서 생성된다(scripts/gen-recipes.mjs). 여기를 고치지 말고 파일을 고친다 -->
 ```tsx
-<div className="flex h-screen items-stretch justify-center bg-(--sys-color-bg-neutralLight) p-sd-24">
-  <SLoginCard
-    product="AI assistant"
-    title="셀메이트 AI 어시스턴트와 함께 자료 찾는 시간은 줄이고, 업무는 빠르게!"
-    description="(사내 답변은 사내 문서를 기반으로 답변합니다.)"
-    onLogin={signIn}
-    footerNote="계정이 없다면 담당자에게 문의를 요청해 주세요."
-    bottomAction={
-      <STextLink label="관리자 로그인" icon="settingOutline" rightArrow="chevron" onClick={goAdmin} />
-    }
-  />
-</div>
+import { SLoginCard, STextLink } from 'sellmate-design-system-react';
+import { useNavigate } from './router';
+
+/**
+ * 로그인 전이라 앱 셸이 없다 — AppShell 을 쓰지 않고 회색 바탕 위에 카드 하나만 선다.
+ * 카드는 화면을 잡지 않으므로 바깥 한 겹은 앱이 만든다. 그 한 겹이 하는 일은 셋뿐이다:
+ *   바탕·여백 / items-stretch 로 카드가 높이를 채우게 / justify-center 로 가로 가운데
+ */
+export default function LoginPage() {
+  const navigate = useNavigate();
+
+  return (
+    // 여백은 카드가 최소 폭을 지킬 수 있는 값으로 둔다 — 카드 폭은 className 으로 박지 않는다
+    <div className="flex h-screen items-stretch justify-center bg-bg-neutralLight p-sd-24">
+      <SLoginCard
+        product="AI assistant"
+        title="셀메이트 AI 어시스턴트와 함께 자료 찾는 시간은 줄이고, 업무는 빠르게!"
+        description="(사내 답변은 사내 문서를 기반으로 답변합니다.)"
+        // 로그인 버튼은 카드가 그린다 — 동작만 넘긴다
+        onLogin={() => navigate('/auth/sso')}
+        footerNote="계정이 없다면 담당자에게 문의를 요청해 주세요."
+        // 로그인과 성격이 다른 보조 진입점만 — STextLink 하나. 버튼을 세우지 않는다
+        bottomAction={
+          <STextLink
+            label="관리자 로그인"
+            icon="settingOutline"
+            rightArrow="chevron"
+            onClick={() => navigate('/admin/login')}
+          />
+        }
+      />
+    </div>
+  );
+}
 ```
+<!-- /recipe -->
 
 **바깥 한 겹은 앱이 만든다.** 카드는 화면을 잡지 않는다 — 덕분에 로그인 화면 밖(세션 만료 재인증 등)에서도 같은 카드를 그대로 쓴다. 그 한 겹은 위 세 가지만 하면 되고, 그 이상은 하지 않는다.
 
-- 바탕은 `bg-(--sys-color-bg-neutralLight)`, 여백은 `p-sd-24`. **여백은 카드가 최소 폭(368px)을 지킬 수 있는 값으로 둔다** — 좌우 합이 창 폭에서 368px 을 남기지 못하면 카드가 넘친다
+- 바탕은 `bg-bg-neutralLight`, 여백은 `p-sd-24`. **여백은 카드가 최소 폭(368px)을 지킬 수 있는 값으로 둔다** — 좌우 합이 창 폭에서 368px 을 남기지 못하면 카드가 넘친다
 - `items-stretch` — 카드가 남은 높이를 채운다. `items-center` 로 두면 카드가 내용 높이로 줄어든다
 - `justify-center` — 카드를 가로 가운데에
 
@@ -2612,9 +2851,23 @@ export default function ProductDetailPage() {
 
 앱 셸 없이 서는 또 하나의 화면이다. 별도 브라우저 창으로 열리는 전용 라우트이므로 `SLayout`·`SGnb`·`SPage` 가 없고, 창을 통째로 `SPopup` 하나가 채운다. 무엇을 팝업으로 열지는 §3-3-1·§3-3-3 에서 고르고, 여기서는 그 라우트의 골격만 다룬다.
 
+<!-- recipe:src/recipes/TransferOrderPopupPage.tsx — 아래 코드 블록은 이 파일에서 생성된다(scripts/gen-recipes.mjs). 여기를 고치지 말고 파일을 고친다 -->
 ```tsx
+import { useState } from 'react';
+import {
+  SKeyValueTable,
+  SPopup,
+  SSectionHeaderCard,
+  STable,
+  STabs,
+  type SKeyValueField,
+  type STableColumn,
+} from 'sellmate-design-system-react';
+import { ORDER_TABS, useTransferOrder } from './api';
+import { useParams } from './router';
+
 // 1) 목록에서 별도 창을 연다 — 창 크기 = 콘텐츠 크기
-function openDetailPopup(orderId: string) {
+export function openTransferOrderPopup(orderId: string) {
   window.open(
     `${window.location.origin}/popup/transfer-orders/${orderId}`,
     `transfer-order-${orderId}`,
@@ -2622,21 +2875,55 @@ function openDetailPopup(orderId: string) {
   );
 }
 
-// 2) 그 라우트의 루트는 SPopup 하나다 (조회만 → 푸터 없음)
+const summaryFields: SKeyValueField[][] = [
+  [
+    { name: 'from', label: '출발 창고', type: 'text' },
+    { name: 'to', label: '도착 창고', type: 'text' },
+    { name: 'requestedAt', label: '요청일', type: 'text' },
+  ],
+];
+
+// 정렬·폭은 값의 성격에서 나온다 (§3-4) — 코드·일시·닫힌 집합은 center, 양은 right, 자유 텍스트는 기준 폭
+const itemColumns: STableColumn[] = [
+  { name: 'sku', label: '품목 코드', field: 'sku', width: 140, align: 'center' },
+  { name: 'name', label: '품목명', field: 'name', width: 240 },
+  { name: 'qty', label: '수량', field: 'qty', width: 100, align: 'right' },
+];
+
+const historyColumns: STableColumn[] = [
+  { name: 'at', label: '일시', field: 'at', width: 160, align: 'center' },
+  // 처리 종류는 닫힌 값 집합(요청·승인 …) → center
+  { name: 'action', label: '처리', field: 'action', width: 100, align: 'center' },
+  { name: 'by', label: '처리자', field: 'by', width: 120 },
+];
+
+// 2) 그 라우트의 루트는 SPopup 하나다 — 앱 셸(SLayout·SGnb·SPage)이 없다. 조회만 하므로 푸터도 없다
 export default function TransferOrderPopupPage() {
+  const { orderId } = useParams();
+  const order = useTransferOrder(orderId);
+  const [tab, setTab] = useState('items');
+
   return (
     // h-screen 으로 창 높이를 잡는다 — 이게 없으면 본문이 창 밖으로 자란다
     <SPopup className="h-screen" popupTitle="이동 오더 상세">
       {/* 본문 패딩은 SPopup 이 토큰으로 넣는다 — p-sd-* 로 덮어쓰지 않는다 */}
       <div className="flex flex-col gap-sd-12">
-        <SSectionHeaderCard>…</SSectionHeaderCard>
-        <STabs value={tab} tabs={TABS} onValueChange={setTab} />
-        <STable columns={columns} rows={rows} rowKey="id" />
+        {/* 카드 안이 표 하나뿐이라 padding="none" 으로 가장자리까지 채운다 — 표는 자기 테두리를 끄고 위 모서리를 죽인다 (§2-2) */}
+        <SSectionHeaderCard title={order.orderId} padding="none">
+          <SKeyValueTable fields={summaryFields} values={order} bordered={false} radius="useTop" />
+        </SSectionHeaderCard>
+        <STabs value={tab} tabs={ORDER_TABS} onValueChange={setTab} />
+        {tab === 'items' ? (
+          <STable columns={itemColumns} rows={order.items} rowKey="id" resizable />
+        ) : (
+          <STable columns={historyColumns} rows={order.history} rowKey="id" resizable />
+        )}
       </div>
     </SPopup>
   );
 }
 ```
+<!-- /recipe -->
 
 **높이는 라우트가 준다 — `SPopup` 에 `h-screen` 을 준다.** `SPopup` 자체는 부모 높이를 채우도록만 되어 있어서, 부모(라우트 루트·`body`)가 높이를 정해 주지 않으면 100% 가 풀려 본문이 창 밖으로 자란다. 그러면 헤더·푸터가 위아래로 밀려 창 안에 보이지 않는다. `h-screen` 이면 `html`·`body`·마운트 루트에 전역 CSS 를 걸지 않고도 창 높이가 바로 들어온다. (`body` 여백은 0 이어야 한다 — Tailwind preflight 가 이미 0 으로 만든다.)
 
@@ -2644,28 +2931,96 @@ export default function TransferOrderPopupPage() {
 
 **표를 담으면 본문이 아니라 표가 스크롤한다.** 본문이 통째로 스크롤되면 표 헤더와 페이지네이션 바가 위아래로 밀려 사라진다. `SPopup` 의 본문은 이미 남은 높이를 잡고 있으므로, 본문 루트에 `h-full min-h-0` 으로 세로 축을 잇고 표에 `min-h-0 flex-1` 을 준다. **툴바+표를 묶은 `div` 도 사슬의 한 칸이라 거기에도 `min-h-0 flex-1` 이 필요하다** (§4-2 목록 페이지와 같은 사슬이다 — 한 칸만 끊겨도 표가 높이를 못 잡는데 실패가 조용하다).
 
+<!-- recipe:src/recipes/ExcelFilePopupPage.tsx — 아래 코드 블록은 이 파일에서 생성된다(scripts/gen-recipes.mjs). 여기를 고치지 말고 파일을 고친다 -->
 ```tsx
-<SPopup
-  className="h-screen"
-  popupTitle="엑셀 파일 관리"
-  showFooter                        // 확정할 작업이 있을 때만 (§3-3-3)
-  submitButton={{ label: '저장' }}
-  onSubmit={save}
->
-  <div className="flex h-full min-h-0 flex-col gap-sd-12">
-    <SKeyValueTable fields={filterFields} values={filters} search
-      onChange={({ values }) => setFilters(values)} onSearch={fetchList} />
+import { useState } from 'react';
+import {
+  SPopup,
+  SSearchInput,
+  STable,
+  STableBar,
+  type SRow,
+  type STableColumn,
+} from 'sellmate-design-system-react';
+import { applyExcelFiles, useExcelFiles } from './api';
 
-    {/* 툴바+표 = 한 블록. 이 div 가 사슬의 한 칸이다 (§2-0) */}
-    <div className="flex min-h-0 flex-1 flex-col">
-      <STableBar className="border-b-0" total={total} />
-      {/* 표만 자기 안에서 스크롤한다 — 필터·툴바·푸터는 늘 보인다 */}
-      <STable className="min-h-0 flex-1" columns={columns} rows={rows} rowKey="id"
-        pagination={{ currentPage, lastPage }} />
-    </div>
-  </div>
-</SPopup>
+// 정렬·폭은 값의 성격에서 나온다 (§3-4) — 자유 텍스트는 기준 폭 + resizable, 일자는 center, 양은 right
+const columns: STableColumn[] = [
+  { name: 'fileName', label: '파일명', field: 'fileName', width: 320 },
+  { name: 'uploadedAt', label: '업로드일', field: 'uploadedAt', width: 120, align: 'center' },
+  {
+    name: 'rows',
+    label: '행 수',
+    field: 'rows',
+    width: 100,
+    align: 'right',
+    format: (v: unknown) => Number(v).toLocaleString(),
+  },
+];
+
+/**
+ * 표를 담은 팝업 — 본문이 아니라 표가 스크롤한다. 툴바·푸터는 늘 보인다.
+ * SPopup 의 본문은 이미 남은 높이를 잡고 있으므로, 본문 루트부터 표까지 세로 축을 잇는다 (§4-2 와 같은 사슬).
+ */
+export default function ExcelFilePopupPage() {
+  // 입력 중인 검색어와 Enter 로 확정된 조회 조건은 따로 든다
+  const [keyword, setKeyword] = useState('');
+  const [query, setQuery] = useState({ keyword: '', page: 1, rowsPerPage: 20 });
+  const [selected, setSelected] = useState<SRow[]>([]);
+  const { rows, total, lastPage } = useExcelFiles(query);
+
+  const save = () => applyExcelFiles(selected.map(row => Number(row.id)));
+
+  return (
+    <SPopup
+      className="h-screen"
+      popupTitle="엑셀 파일 관리"
+      showFooter // 확정할 작업이 있을 때만 (§3-3-3)
+      submitButton={{ label: '저장', disabled: !selected.length }}
+      onSubmit={save}
+    >
+      {/* 툴바+표 = 한 블록이자 본문 루트. h-full min-h-0 → 표의 min-h-0 flex-1 로 세로 축이 이어진다.
+          필터 표가 위에 더 서면 이 블록을 한 겹 감싸고 여기에 min-h-0 flex-1 을 준다 (§4-2 와 같은 사슬) */}
+      <div className="flex h-full min-h-0 flex-col">
+        {/* 조건이 검색어 하나뿐이면 필터 표를 세우지 않는다 — 목록을 좁히기만 하는 검색어는
+            폼 필드가 아니라 SSearchInput 이다 (§3-7-1). 툴바 우측에 둔다 */}
+        <STableBar
+          className="border-b-0"
+          total={total}
+          selected={selected.length}
+          rightActions={
+            <SSearchInput
+              value={keyword}
+              onValueChange={value => {
+                setKeyword(value);
+                // 지우기(×)는 값만 비우고 onSearch 를 부르지 않는다 — 걸려 있던 조건도 여기서 함께 푼다
+                if (!value) setQuery(q => ({ ...q, keyword: '', page: 1 }));
+              }}
+              onSearch={value => setQuery(q => ({ ...q, keyword: value, page: 1 }))}
+              placeholder="파일명 검색"
+              width="md"
+              clearable
+            />
+          }
+        />
+        <STable
+          className="min-h-0 flex-1"
+          columns={columns}
+          rows={rows}
+          rowKey="id"
+          resizable
+          selectable
+          selected={selected}
+          onSelectedChange={setSelected}
+          pagination={{ page: query.page, rowsPerPage: query.rowsPerPage, lastPage }}
+          onPageChange={page => setQuery(q => ({ ...q, page }))}
+        />
+      </div>
+    </SPopup>
+  );
+}
 ```
+<!-- /recipe -->
 
 조회만 하고 표가 없는 팝업은 이 사슬이 필요 없다 — 본문이 통째로 스크롤되어도 헤더는 고정이고 밀려날 푸터가 없다.
 
@@ -2719,7 +3074,7 @@ export default function TransferOrderPopupPage() {
 - [ ] 서버에서 페이지 단위로 받는 `SSelect` 에 `onReachEnd` 와 `hasMore`·`loading`·`serverSearch` 를 함께 줬는가, 늦게 온 응답을 버리는 cleanup 이 있는가 (§3-7-2 — 렌더 최적화는 DS 가 알아서 한다)
 - [ ] `SKeyValueTable` 의 짧은 행에 `tdColSpan` 을 주어 전체 열 수를 채웠는가 (§4-3 — 안 채우면 그 구간의 행 구분선이 끊긴다)
 - [ ] 날짜·시간 필드가 섞인 `SKeyValueTable` 에서 오른쪽 끝을 맞출지 정했는가 (§4-3 `fieldWidth` — 필터는 `"fill"`, 등록·수정 폼은 기본값. 필드마다 `maxWidth` 를 주지 않는다)
-- [ ] 하단 버튼이 양끝 분리(`justify-between`)이고, 되돌리기가 왼쪽 끝 · 실행이 오른쪽 끝인가
+- [ ] 하단 버튼이 양끝 분리(`justify-between`)이고, 되돌리기가 왼쪽 끝 · 실행이 오른쪽 끝인가 (되돌리는 액션이 없어도 양끝 분리는 그대로 — 오른쪽에 모으지 않고 위계가 낮은 쪽을 왼쪽 끝에 둔다)
 - [ ] 페이지에 `color="primary"` 채움 버튼이 **1개뿐**인가 (`danger` 채움도 1개, `SDropdownButton` 포함)
 - [ ] 버튼 `size` 가 위치 규칙과 맞는가 (행 내부 `xs` / 화면 액션 `sm` / 모달 푸터 `md`)
 - [ ] 파괴 액션의 채움/outline 이 **적용 범위 + 위험도** 기준과 맞는가