@wipco/sdui 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -16,10 +16,15 @@ interface SduiAdapter {
     /**
      * submitForm 등 JSON API 호출. 성공 시 응답 JSON을, 실패 시
      * Error(사용자에게 보여줄 메시지)를 던진다.
+     *
+     * `signal`은 호출부가 중단할 수 있는 조회(목록 재조회 등)에서만 넘어온다 —
+     * 선택 사항이라 무시해도 계약은 성립하지만, 넘겨받은 호스트는 자기 클라이언트에
+     * 그대로 흘려 보내면 파라미터가 바뀔 때 이전 요청이 실제로 끊긴다.
      */
     fetch?: (path: string, init: {
         method: string;
         body?: unknown;
+        signal?: AbortSignal;
     }) => Promise<unknown>;
     /** download 액션용 원시 fetch. 기본: fetch(path, { credentials: 'include' }) */
     rawFetch?: (path: string) => Promise<Response>;
@@ -39,8 +44,100 @@ interface SduiAdapter {
      * 어긋나지 않게 한다. 기본: window.history.replaceState.
      */
     replaceQuery?: (params: URLSearchParams) => void;
+    /**
+     * 스펙이 준 **자산 URL**을 브라우저가 자동으로 받아 오기 직전에 가로채는 자리.
+     *
+     * `fetch`·`navigate`와 결정적으로 다르다. 저 둘은 어댑터가 **호출을 소유**하므로
+     * 구현을 비워 두면 아무 일도 안 일어난다. 자산은 그렇지 않다 — `<img src>`나
+     * `background-image: url(…)`이 DOM에 닿는 순간 요청을 내는 것은 **브라우저**이고,
+     * 어댑터는 그 자리에 없다. 그래서 값이 DOM에 닿기 전에 갈아 끼우는 훅이 필요하다.
+     *
+     * @param url 스펙에서 온 원본 URL(상대·절대 모두).
+     * @param ctx 어느 컴포넌트의 어느 자리에서 왔는지.
+     * @returns 실제로 쓸 URL. `null`이면 그 프롭(또는 CSS 선언 하나)을 통째로 뺀다.
+     *
+     * 기본 구현은 **항등함수**다(`defaultAdapter.resolveAsset`). 진짜 앱은 자기 세션으로
+     * 자기 서버의 이미지를 봐야 하므로 여기서 무엇이든 바꾸면 그게 곧 회귀다.
+     * 바꾸는 쪽은 편집기 캔버스 하나뿐이다 — 저장도 안 된 남의 스펙 텍스트를 편집자의
+     * 특권 세션으로, 사용자가 방문 의사를 밝힌 적 없이 그리는 유일한 자리라서다.
+     */
+    resolveAsset?: SduiAssetResolver;
+    /**
+     * **이 화면은 진짜가 아니다** — 편집기 캔버스처럼 "저장도 안 된 남의 스펙을 편집자의
+     * 특권 세션으로 그리는" 자리라는 선언.
+     *
+     * 위의 어떤 필드로도 대신할 수 없어서 따로 둔다. `fetch`·`navigate`는 어댑터가
+     * **호출을 소유**하므로 막으면 그만이고, `resolveAsset`은 브라우저가 소유하는 자산
+     * 요청을 값 교체로 가로챈다. 그런데 세 번째 부류가 있다 — **컴포넌트가 자기 데이터
+     * 클라이언트로 직접 조회하는 경우**다. 소비 앱의 `RemoteSearchResults`는 TanStack
+     * Query로 조회하는데, 그 캐시는 모듈 싱글턴이라 어댑터가 끼어들 자리가 아예 없고,
+     * `queryFn`만 어댑터로 돌리면 캔버스가 돌려준 빈 응답이 **전역 캐시에 실려** 편집기를
+     * 닫은 뒤 진짜 페이지까지 오염시킨다. 그런 컴포넌트는 "요청을 보낼지 말지"를 스스로
+     * 정해야 하고, 그 판단 재료가 이 플래그다.
+     *
+     * 검토하고 버린 대용 신호 둘 — 둘 다 **"샌드박스"가 아닌 것을 샌드박스로 읽는다**:
+     * - `assetResolverOf(adapter) !== null`: CDN 리라이팅처럼 **정당하게** `resolveAsset`을
+     *   꽂은 호스트가 목록을 통째로 잃는다.
+     * - `resolveAsset('/__probe', …)`가 원본을 안 돌려주는지 되묻는 행동 프로브: 위와 같은
+     *   오판을 하면서 의도가 코드에 안 남는다.
+     *
+     * 기본값은 "선언 없음"(=진짜 앱)이다. 진짜 앱 어댑터에는 이 키가 아예 없으므로
+     * {@link useSduiSandbox}는 `false`를 돌려주고 **기존 동작이 한 글자도 안 바뀐다.**
+     * 켜는 곳은 편집기 캔버스 하나뿐이다.
+     */
+    sandbox?: boolean;
+}
+/** {@link SduiAdapter.resolveAsset}가 받는 맥락 — 어디서 온 URL인지 판단 재료. */
+interface SduiAssetContext {
+    /** 이 URL을 그리는 컴포넌트 이름(스펙의 `component`). */
+    component: string;
+    /** URL이 실린 프롭 이름. 중첩 값이면 그 자리의 키(`items[].src`면 `src`). */
+    prop: string;
+    /**
+     * 브라우저가 이 URL을 **어떤 경로로** 부르는가.
+     * - `attribute` — `<img src>` 같은 DOM URL 속성
+     * - `css` — 인라인 스타일 선언값 안의 `url()`
+     *
+     * 둘을 구분하는 이유: 되돌려 줄 수 있는 값이 다르다. 속성 자리에는 자리표시자 이미지를
+     * 넣어 박스를 유지할 수 있지만, `cursor: url(…)`에 이미지를 넣으면 CSS가 유효하지 않고
+     * (키워드 대체값이 필요하다) `mask-image`에 넣으면 요소 자체가 그 모양으로 깎인다.
+     */
+    kind: 'attribute' | 'css';
+    /** `kind: 'css'`일 때 그 선언의 속성명. React 표기 그대로다(`backgroundImage`). */
+    cssProperty?: string;
 }
-declare const defaultAdapter: Required<Pick<SduiAdapter, 'navigate' | 'fetch' | 'rawFetch'>> & SduiAdapter;
+type SduiAssetResolver = (url: string, ctx: SduiAssetContext) => string | null;
+declare const defaultAdapter: Required<Pick<SduiAdapter, 'navigate' | 'fetch' | 'rawFetch' | 'resolveAsset'>> & SduiAdapter;
+/**
+ * **스스로 URL을 만드는 컴포넌트**를 위한 자산 관문.
+ *
+ * 렌더러의 프롭 순회는 "스펙이 준 URL"만 본다. 그런데 실제 우회는 프롭이 없어도 난다 —
+ * 소비 앱의 `QRDisplay`는 `<img src={apiUrl('/qr?data=…')}>`처럼 URL을 **안에서 만들어**
+ * 붙이므로 프롭 검사에 걸릴 문자열이 애초에 없다. 동일 오리진이라 쿠키까지 실린다.
+ * 그런 컴포넌트는 이 훅으로 스스로 관문을 통과시켜야 한다.
+ *
+ *   const resolveAsset = useSduiAssetResolver();
+ *   const src = resolveAsset(apiUrl(`/qr?data=${value}`), { component: 'QRDisplay', prop: 'src', kind: 'attribute' });
+ *   return src === null ? null : <img src={src} alt="" />;
+ *
+ * 렌더러 밖(드롭인 사용)이면 항등함수를 돌려준다 — 감싸지 않은 소비자의 동작은 바뀌지 않는다.
+ */
+declare function useSduiAssetResolver(): SduiAssetResolver;
+/**
+ * **지금 그려지는 곳이 샌드박스(편집기 캔버스)인가.**
+ *
+ * 스스로 데이터를 조회하는 컴포넌트가 "요청을 아예 내지 않는다"를 고를 때 쓴다.
+ * {@link useSduiAssetResolver}와 나란한 자리지만 성질이 다르다 — 저쪽은 이미 만들어진
+ * URL을 **갈아 끼우는** 값 변환이고, 이쪽은 조회를 **시작조차 하지 않게** 하는 분기다.
+ * 자산은 값을 바꾸면 끝이지만 조회는 캐시·구독·재조회가 딸려 와서, 늦게 막으면
+ * 이미 늦는다(빈 응답이 공유 캐시에 남는다).
+ *
+ * 렌더러 밖(드롭인 사용)이면 `false`다 — 감싸지 않은 소비자의 동작은 바뀌지 않는다.
+ *
+ *   const sandbox = useSduiSandbox();
+ *   const { data } = useAppQuery(sandbox ? null : endpoint);   // 조회 자체를 끈다
+ */
+declare function useSduiSandbox(): boolean;
 
 /**
  * 권한 게이트 — 통과하면 children, 실패하면 fallback 슬롯(없으면 아무 것도)을 렌더한다.
@@ -402,6 +499,102 @@ interface DialogProps extends Omit<React__default.HTMLAttributes<HTMLDivElement>
 }
 /** 모달 본체. 오버레이가 가장 가까운 포지셔닝 조상을 채운다 — SDUI에서는 SduiDialog 래퍼가 뷰포트에 고정한다. */
 declare function Dialog({ title, subtitle, icon, tone, size, footer, onClose, children, className, ...rest }: DialogProps): React__default.JSX.Element;
+/** 배타 뷰 전환 스위치. 항목 2~4개까지, 그보다 많으면 Select다. */
+interface SegmentedItem {
+    value: string;
+    label?: string;
+    /** 앞에 붙일 아이콘 이름 */
+    icon?: string;
+}
+interface SegmentedControlProps extends Omit<React__default.HTMLAttributes<HTMLDivElement>, 'onChange'> {
+    items: SegmentedItem[];
+    value: string;
+    onChange?: (value: string) => void;
+    /** md(24px 항목, 기본) · lg(30px) */
+    size?: 'md' | 'lg';
+    className?: string;
+}
+/**
+ * 목록/카드, 2D/3D, 일/주/월처럼 하나만 고르는 뷰 전환.
+ *
+ * `search/SearchResults.tsx`가 "라이브러리에 SegmentedControl이 없다"는 이유로
+ * 안에 `ViewToggle` 사본을 들고 있었다. 이 컴포넌트가 그 사본의 원본이다.
+ */
+declare function SegmentedControl({ items, value, onChange, size, className, ...rest }: SegmentedControlProps): React__default.JSX.Element;
+/** 사람·팀·자산의 신원 표식. */
+interface AvatarProps extends React__default.HTMLAttributes<HTMLSpanElement> {
+    /** 이니셜과 title에 쓰인다 */
+    name?: string;
+    /** 이미지 URL — 있으면 이니셜을 대신한다 */
+    src?: string;
+    /** hex(기본, 심볼 실루엣) · round(사람) · square(자산) */
+    shape?: 'hex' | 'round' | 'square';
+    /** xs 20 · sm 24 · md 28(기본) · lg 36 · xl 48 px */
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    /** brand 네이비(기본) · muted 회색 · accent 레드 */
+    tone?: 'brand' | 'muted' | 'accent';
+    className?: string;
+}
+/** 사람/자산 표식. 기본은 육각형 — 심볼의 실루엣이다. */
+declare function Avatar({ name, src, shape, size, tone, className, ...rest }: AvatarProps): React__default.JSX.Element;
+/** 프로젝트에서 개별 객체까지의 위치. 4단계를 넘으면 가운데를 접는다. */
+interface BreadcrumbItem {
+    label: React__default.ReactNode;
+    href?: string;
+    icon?: string;
+    onClick?: () => void;
+}
+interface BreadcrumbProps extends React__default.HTMLAttributes<HTMLElement> {
+    items: BreadcrumbItem[];
+    className?: string;
+}
+/** 계보 표시. 마지막 항목은 현재 객체이므로 링크가 아니다. */
+declare function Breadcrumb({ items, className, ...rest }: BreadcrumbProps): React__default.JSX.Element;
+/** 후보가 전부 보이는 배타 선택. 5개 이상이면 Select다. */
+interface RadioProps extends React__default.InputHTMLAttributes<HTMLInputElement> {
+    label?: React__default.ReactNode;
+    description?: React__default.ReactNode;
+    disabled?: boolean;
+}
+/** 2~4개 후보를 다 보여 주는 라디오. Checkbox와 마크업을 공유한다(.wp-check). */
+declare function Radio({ label, description, disabled, className, ...rest }: RadioProps): React__default.JSX.Element;
+/** 주 내비게이션 목록. 활성 항목에 빨간 에지 마커가 붙는다. */
+interface SidebarNavItem {
+    value: string;
+    label: React__default.ReactNode;
+    icon?: string;
+    meta?: React__default.ReactNode;
+    href?: string;
+}
+interface SidebarNavSection {
+    label?: React__default.ReactNode;
+    items: SidebarNavItem[];
+}
+interface SidebarNavProps extends Omit<React__default.HTMLAttributes<HTMLElement>, 'onSelect'> {
+    sections: SidebarNavSection[];
+    value?: string;
+    onSelect?: (value: string) => void;
+    /** 아이콘만 남기는 56px 레일 */
+    collapsed?: boolean;
+    /** 흰 표면(설정 하위 내비) 위에 쓰는 밝은 변형 */
+    light?: boolean;
+    className?: string;
+}
+/** 네이비 사이드바의 주 내비게이션. 섹션 + 항목. */
+declare function SidebarNav({ sections, value, onSelect, collapsed, light, className, ...rest }: SidebarNavProps): React__default.JSX.Element;
+/** 아이콘 전용 컨트롤·잘린 값에 붙이는 hover/focus 힌트. */
+interface TooltipProps extends React__default.HTMLAttributes<HTMLSpanElement> {
+    label: React__default.ReactNode;
+    /** 단축키 칩, 예: "⌘K" */
+    shortcut?: string;
+    placement?: 'top' | 'bottom' | 'left' | 'right';
+    /** 여러 줄 허용(최대 240px) */
+    wrap?: boolean;
+    children?: React__default.ReactNode;
+    className?: string;
+}
+/** hover 힌트. 트리거를 감싸며 위치는 CSS가 잡는다 — 포털을 쓰지 않는다. */
+declare function Tooltip({ label, shortcut, placement, wrap, children, className, ...rest }: TooltipProps): React__default.JSX.Element;
 
 interface GridProps {
     /** wp-grid--N 프리셋 */
@@ -500,13 +693,27 @@ declare function Divider({ style }: {
     style?: React__default.CSSProperties;
 }): React__default.JSX.Element;
 
+/** SduiRenderer가 제공하는 액션 디스패처. 레지스트리의 복합 컴포넌트가 선언적 액션을 실행할 때 쓴다. */
+type SduiDispatch = (action: SduiAction, eventValue?: unknown) => void;
+declare function useSduiDispatch(): SduiDispatch;
+
 /**
  * 목록 원격 조회 어댑터.
  *
  * core는 특정 HTTP 클라이언트에 묶이지 않는다 — ERP는 SWR(useErpQuery)로 조회했지만
  * 라이브러리는 "endpoint + 파라미터 → { data, total }" 한 줄짜리 계약만 요구하고,
  * 호스트가 자기 클라이언트(TanStack Query, SWR, 사내 fetch 래퍼…)를 끼워 넣는다.
- * 주입이 없으면 브라우저 fetch로 동작한다(어댑터를 안 준 SduiRenderer와 같은 정책).
+ *
+ * 조회 함수를 고르는 순서는 셋이다:
+ *
+ *  1. `SduiSearchDataProvider`로 **명시 주입**한 fetcher — 가장 세다. 조회를 통째로 소유하는
+ *     소비자(ERP RemoteSearchResults 등)의 뜻을 다른 무엇도 덮지 않는다.
+ *  2. 렌더러 어댑터의 `fetch` — 호스트가 자기 인증·에러 처리를 꽂아 둔 자리다. 여기를 거치면
+ *     소비 앱은 세션 규약을 그대로 태우고, 편집기 캔버스처럼 어댑터로 바깥을 막아 둔
+ *     자리에서는 목록 조회도 **함께 막힌다**. 예전에는 이 경로만 잠금 밖이라, 캔버스가
+ *     뜨는 것만으로 저장하지도 않은 스펙이 운영 API를 세션 쿠키와 함께 때렸다.
+ *  3. 둘 다 없으면 브라우저 fetch(어댑터를 안 준 SduiRenderer와 같은 정책) — 감싸지 않은
+ *     드롭인 소비자의 동작을 바꾸지 않기 위한 폴백이다.
  */
 
 interface SearchRow {
@@ -536,6 +743,9 @@ interface RemotePageState {
 /**
  * endpoint+params 조회 훅. 라이브러리 안에 캐시를 두지 않는다(호스트 클라이언트의 몫) —
  * 대신 직전 페이지를 유지해(keepPreviousData 상당) 페이지 이동 중 목록이 깜빡이지 않게 한다.
+ *
+ * 중단 신호는 fetcher에 넘기지만 호스트가 무시할 수도 있다(어댑터 계약상 선택 사항) —
+ * 그래서 늦게 도착한 응답은 아래 `alive` 검사로 한 번 더 버린다.
  */
 declare function useRemoteSearchPage(endpoint: string, params: URLSearchParams): RemotePageState;
 
@@ -661,6 +871,20 @@ interface SearchFilter {
         value: string;
     }[];
 }
+/**
+ * 목록/카드 전환 버튼 한 칸.
+ *
+ * 예전에는 이 두 칸(`목록`/`카드`)이 코드에 박혀 있어 스펙이 라벨·아이콘·순서를
+ * 바꿀 수 없었고, `disableGrid`/`disableList`로 **끄는 것만** 가능했다.
+ * 이제 `views`로 목록 자체를 정할 수 있고, 두 disable 프롭은 그 축약형으로 남는다.
+ */
+interface SearchViewItem {
+    value: 'grid' | 'list';
+    /** 생략 시 기본 아이콘 — list=list, grid=layout-grid */
+    icon?: string;
+    /** 생략 시 기본 라벨 — list=목록, grid=카드 */
+    label?: string;
+}
 interface GridCardRow<T> {
     icon?: React__default.ReactNode | ((item: T) => React__default.ReactNode);
     label?: React__default.ReactNode | ((item: T) => React__default.ReactNode);
@@ -690,6 +914,14 @@ interface SearchResultsProps<T> {
     leftFilters?: SearchFilter[];
     rightFilters?: SearchFilter[];
     initialView?: 'grid' | 'list';
+    /**
+     * 노출할 보기 목록. 생략하면 목록/카드 두 칸이 기본값이고,
+     * 그때만 `disableGrid`/`disableList`가 목록을 깎는다(둘 다 오면 views가 이긴다).
+     * 한 칸만 남으면 전환 버튼 자체를 그리지 않는다.
+     */
+    views?: SearchViewItem[];
+    /** 페이지당 건수 선택지. 생략 시 [10, 20, 50, 100]. 첫 값이 기본 페이지 크기다. */
+    pageSizes?: number[];
     className?: string;
     /** 검색/필터/페이지 파라미터 (controlled) */
     searchParams: URLSearchParams;
@@ -713,9 +945,96 @@ interface SearchResultsProps<T> {
      */
     virtual?: boolean | number;
 }
+/**
+ * 스펙이 준 페이지 크기 목록을 다듬는다 — 양의 정수만, 중복 제거, 오름차순.
+ * 쓸 값이 하나도 없으면 undefined를 돌려 기본 선택지를 쓰게 한다.
+ */
+declare function normalizePageSizes(sizes: number[] | undefined): number[] | undefined;
 declare function SearchResults<T extends {
     id: string;
-}>({ item, columns, gridConfig, leftFilters, rightFilters, initialView, className, searchParams, onParamsChange, actions, disableGrid, disableList, onRowClick, title, headerActions, isLoading, hideHeader, advancedSearchFields, searchPlaceholder, virtual, }: SearchResultsProps<T>): React__default.JSX.Element;
+}>({ item, columns, gridConfig, leftFilters, rightFilters, initialView, views, pageSizes, className, searchParams, onParamsChange, actions, disableGrid, disableList, onRowClick, title, headerActions, isLoading, hideHeader, advancedSearchFields, searchPlaceholder, virtual, }: SearchResultsProps<T>): React__default.JSX.Element;
+
+/**
+ * 셀 표현 어휘 — 목록 컬럼의 셀과 카드 행의 값이 **같은 규칙**을 쓴다.
+ *
+ * 예전에는 스펙이 고를 수 있는 표현이 `badge` 하나뿐이었고 나머지는 `row[key]` 원문
+ * 출력이었다. 밑에 깔린 `SearchColumn.render`는 임의의 노드를 그릴 수 있는데 스펙에는
+ * 그 역량이 두 종류(원문/배지)로만 열려 있었다는 뜻이다. 여기서 그 구멍을 메운다.
+ *
+ * 규약 두 가지:
+ * - **모르는 type은 원문으로 강등한다.** 스펙은 신뢰할 수 없는 입력이고, 컬럼 하나 때문에
+ *   목록 전체가 비면 안 된다. 판별 유니언이라 새 type을 더해도 옛 스펙은 그대로 돈다.
+ * - **값을 해석하지 못하면 원문을 그대로 낸다.** ERP는 이미 서식된 문자열(`"12,400,000"`,
+ *   `"2026-07-31 09:00"`)을 내려주는 자리가 많아, 파싱 실패를 빈칸으로 만들면 퇴행이다.
+ */
+
+/** ProgressBar가 받는 톤 */
+type MeterTone = 'brand' | 'success' | 'warning' | 'danger' | 'info';
+/** 값을 그대로 출력한다. cell을 생략한 것과 같으며, 명시하고 싶을 때 쓴다. */
+interface SduiTextCell {
+    type: 'text';
+}
+/** 값을 배지로. 톤은 값별 매핑(없는 값은 neutral). */
+interface SduiBadgeCell {
+    type: 'badge';
+    toneMap?: Record<string, BadgeTone>;
+}
+/** 값을 태그로. 선행 점 색은 값별 매핑(CSS 색상 문자열). */
+interface SduiTagCell {
+    type: 'tag';
+    colorMap?: Record<string, string>;
+    filled?: boolean;
+}
+/**
+ * 값을 링크로. `to`는 `/assets/{id}` 처럼 행의 필드를 `{키}`로 끼워 넣는 경로 템플릿이고,
+ * 클릭하면 navigate 액션이 나간다(렌더러가 대상 안전성을 다시 검사한다).
+ */
+interface SduiLinkCell {
+    type: 'link';
+    to: string;
+    /** 링크 문구로 쓸 필드 — 생략하면 컬럼 자신의 값 */
+    labelKey?: string;
+    icon?: string;
+}
+/** 값을 진행 막대로. 분모는 maxKey(행의 필드) → max → 100 순으로 정한다. */
+interface SduiProgressCell {
+    type: 'progress';
+    max?: number;
+    maxKey?: string;
+    tone?: MeterTone;
+    showValue?: boolean;
+}
+/** 값을 아이콘으로. iconMap에 없는 값은 icon(공통 기본)으로, 그것도 없으면 원문으로. */
+interface SduiIconCell {
+    type: 'icon';
+    iconMap?: Record<string, string>;
+    icon?: string;
+    /** 아이콘 뒤에 값도 적는다 */
+    withLabel?: boolean;
+}
+/**
+ * 숫자 서식(ko-KR 천단위) + 접두/접미. 통화는 `{ type:'number', suffix:'원' }`이다 —
+ * `currency` 타입을 따로 두지 않은 이유는 ERP가 원화 단일이고, 그 자리에 필요한 것이
+ * 통화 기호가 아니라 "단위 문자열"이기 때문이다(원·건·개·%·kg).
+ */
+interface SduiNumberCell {
+    type: 'number';
+    /** 소수 자릿수 (기본 0) */
+    digits?: number;
+    prefix?: string;
+    suffix?: string;
+}
+/** 날짜 서식(ko-KR). 파싱되지 않는 값은 원문 그대로. */
+interface SduiDateCell {
+    type: 'date';
+    format?: 'date' | 'datetime' | 'time';
+}
+type SduiCell = SduiTextCell | SduiBadgeCell | SduiTagCell | SduiLinkCell | SduiProgressCell | SduiIconCell | SduiNumberCell | SduiDateCell;
+/**
+ * 셀 스펙 → 렌더 함수. `undefined`를 돌려주면 호출자가 원문을 그대로 출력한다
+ * (표에서는 `<td>{row[key]}</td>`, 카드에서는 값 문자열).
+ */
+declare function cellRenderer(cell: SduiCell | undefined, key: string, dispatch: SduiDispatch): ((row: SearchRow) => React__default.ReactNode) | undefined;
 
 /**
  * SearchResults의 SDUI 어댑터 — 함수 프롭 없이 JSON만으로 검색+목록 화면을 구성한다.
@@ -736,12 +1055,36 @@ interface SduiSearchColumn {
     ratio?: number;
     mono?: boolean;
     strong?: boolean;
-    /** 셀 표현. 생략하면 row[key]를 그대로 출력한다 */
-    cell?: {
-        type: 'badge';
-        /** 값 → Badge 톤 매핑 (없는 값은 neutral) */
-        toneMap?: Record<string, BadgeTone>;
-    };
+    /** 셀 표현. 생략하면 row[key]를 그대로 출력한다 — 어휘는 `cells.tsx` 참고 */
+    cell?: SduiCell;
+}
+/**
+ * 카드 행 표시 조건.
+ * `key`만 주면 "그 값이 비어 있지 않을 때"다. 값이 없는 행을 감춰 카드 높이가
+ * 들쭉날쭉해지지 않게 하는 것이 주 용도라 그것이 기본 의미다.
+ */
+interface SduiRowCondition {
+    key: string;
+    equals?: string | number | boolean;
+    in?: Array<string | number>;
+    notEmpty?: boolean;
+}
+interface SduiGridCardRow {
+    label?: string;
+    valueKey: string;
+    /** 라벨 앞 아이콘 */
+    icon?: string;
+    /** 값 표현 — 컬럼 셀과 같은 어휘 */
+    cell?: SduiCell;
+    /** 조건부 행 */
+    showWhen?: SduiRowCondition;
+}
+/** 카드 우상단 버튼 — 이벤트 값으로 행 객체 전체가 전달된다 */
+interface SduiGridCardAction {
+    label: string;
+    icon?: string;
+    variant?: 'default' | 'destructive' | 'outline';
+    run: SduiAction | SduiAction[];
 }
 interface SduiGridCard {
     titleKey: string;
@@ -750,10 +1093,14 @@ interface SduiGridCard {
         key: string;
         toneMap?: Record<string, BadgeTone>;
     };
-    rows?: Array<{
-        label?: string;
-        valueKey: string;
-    }>;
+    /** 한 열로 쌓는 행 */
+    rows?: SduiGridCardRow[];
+    /** 두 열 배치 — 좌/우 각각의 행 목록. rows와 함께 쓰면 두 열이 위, rows가 아래다 */
+    leftRows?: SduiGridCardRow[];
+    rightRows?: SduiGridCardRow[];
+    /** 카드 맨 아래 보조 문구로 쓸 필드 */
+    noteKey?: string;
+    actions?: SduiGridCardAction[];
 }
 interface SduiSearchAction {
     label: string;
@@ -772,6 +1119,13 @@ interface SduiSearchCommonProps {
     gridCard?: SduiGridCard;
     actions?: SduiSearchAction[];
     initialView?: 'grid' | 'list';
+    /**
+     * 노출할 보기 목록(라벨·아이콘·순서). 생략하면 목록/카드 두 칸이 기본이다.
+     * gridCard 없이 카드 보기를 넣으면 빈 카드가 나오므로 여기서 걸러낸다.
+     */
+    views?: SearchViewItem[];
+    /** 페이지당 건수 선택지. 생략 시 [10, 20, 50, 100] */
+    pageSizes?: number[];
     disableGrid?: boolean;
     disableList?: boolean;
     searchPlaceholder?: string;
@@ -785,7 +1139,7 @@ interface SduiSearchCommonProps {
 interface SduiSearchResultsProps extends SduiSearchCommonProps {
     data: SearchRow[];
 }
-declare function SduiSearchResults({ title, data, columns, fields, leftFilters, rightFilters, gridCard, actions, initialView, disableGrid, disableList, searchPlaceholder, rowClick, headerActions, virtual, }: SduiSearchResultsProps): React__default.JSX.Element;
+declare function SduiSearchResults({ title, data, columns, fields, leftFilters, rightFilters, gridCard, actions, initialView, views, pageSizes, disableGrid, disableList, searchPlaceholder, rowClick, headerActions, virtual, }: SduiSearchResultsProps): React__default.JSX.Element;
 interface RemoteSearchResultsProps extends SduiSearchCommonProps {
     /**
      * 목록 endpoint — page/limit/search/필드키 쿼리를 붙여 조회하고
@@ -795,7 +1149,7 @@ interface RemoteSearchResultsProps extends SduiSearchCommonProps {
     /** 페이지당 행 수 (기본 10) — limit 파라미터의 초기값 */
     pageSize?: number;
 }
-declare function RemoteSearchResults({ title, endpoint, columns, fields, leftFilters, rightFilters, gridCard, actions, initialView, disableGrid, disableList, searchPlaceholder, rowClick, headerActions, virtual, pageSize, }: RemoteSearchResultsProps): React__default.JSX.Element;
+declare function RemoteSearchResults({ title, endpoint, columns, fields, leftFilters, rightFilters, gridCard, actions, initialView, views, pageSizes, disableGrid, disableList, searchPlaceholder, rowClick, headerActions, virtual, pageSize, }: RemoteSearchResultsProps): React__default.JSX.Element;
 
 /**
  * 목록 표 — SearchResults 전용. 내장 `Table`은 정렬 헤더·선택 표시·가상 스크롤을
@@ -950,42 +1304,6 @@ declare const defaultRegistry: {
  */
 declare function createRegistry(extensions: SduiRegistry): SduiRegistry;
 
-/** custom 액션을 앱 코드로 위임하는 확장 지점. */
-type CustomActionHandler = (name: string, payload?: SduiPropValue, value?: unknown) => void;
-/** custom 검증 규칙 구현 — 에러 메시지 또는 null 반환 */
-type CustomValidator = (fieldValue: SduiPropValue | undefined, values: Record<string, SduiPropValue>) => string | null;
-interface SduiRendererProps {
-    page: SduiPage;
-    /** 컴포넌트 어휘 — 생략 시 내장 기본 레지스트리 */
-    registry?: SduiRegistry;
-    /** 내비게이션·API·실시간 연결점 — 생략 시 브라우저 기본 구현 */
-    adapter?: SduiAdapter;
-    /**
-     * page.urlState ↔ URL 쿼리 동기화 여부 (기본 true).
-     * 편집기 미리보기처럼 실제 페이지 라우트가 아닌 곳에 마운트할 때 false로 끈다 —
-     * 안 그러면 미리보기의 상태가 호스트 앱 URL을 오염시킨다.
-     */
-    syncUrlState?: boolean;
-    onCustomAction?: CustomActionHandler;
-    customValidators?: Record<string, CustomValidator>;
-}
-/**
- * 서버(JSON 스펙) 주도 페이지 렌더러.
- * 스펙은 직렬화 가능한 데이터만 담고, 상태·이벤트·폼·내비게이션은 여기서 해석한다.
- */
-declare function SduiRenderer({ page, registry, adapter, syncUrlState, onCustomAction, customValidators, }: SduiRendererProps): React__default.JSX.Element;
-
-/**
- * 스펙 구조 검증기 — 서버(또는 편집기)가 만든 스펙의 형태 오류를 렌더 전에 찾아낸다.
- * 렌더러는 개발 모드에서 이 결과를 콘솔에 경고하고, 관리자 편집기는
- * 저장 전에 같은 검사를 돌려 문제 목록을 보여준다.
- */
-interface SpecIssue {
-    path: string;
-    message: string;
-}
-declare function validateSpec(page: unknown, knownComponents?: Set<string>): SpecIssue[];
-
 /**
  * 권한 판정 주입 지점.
  *
@@ -1027,9 +1345,54 @@ declare function SduiPermissionProvider({ can, children }: SduiPermissionProvide
  */
 declare function useSduiCan(): SduiCanFn;
 
-/** SduiRenderer가 제공하는 액션 디스패처. 레지스트리의 복합 컴포넌트가 선언적 액션을 실행할 때 쓴다. */
-type SduiDispatch = (action: SduiAction, eventValue?: unknown) => void;
-declare function useSduiDispatch(): SduiDispatch;
+/** custom 액션을 앱 코드로 위임하는 확장 지점. */
+type CustomActionHandler = (name: string, payload?: SduiPropValue, value?: unknown) => void;
+/** custom 검증 규칙 구현 — 에러 메시지 또는 null 반환 */
+type CustomValidator = (fieldValue: SduiPropValue | undefined, values: Record<string, SduiPropValue>) => string | null;
+interface SduiRendererProps {
+    page: SduiPage;
+    /** 컴포넌트 어휘 — 생략 시 내장 기본 레지스트리 */
+    registry?: SduiRegistry;
+    /** 내비게이션·API·실시간 연결점 — 생략 시 브라우저 기본 구현 */
+    adapter?: SduiAdapter;
+    /**
+     * page.urlState ↔ URL 쿼리 동기화 여부 (기본 true).
+     * 편집기 미리보기처럼 실제 페이지 라우트가 아닌 곳에 마운트할 때 false로 끈다 —
+     * 안 그러면 미리보기의 상태가 호스트 앱 URL을 오염시킨다.
+     */
+    syncUrlState?: boolean;
+    /**
+     * 권한 판정 — `Can` 게이트가 이 콜백에 질의한다.
+     *
+     * 라이브러리는 권한 모델을 알지 않는다(근거는 permission.tsx 주석). ERP라면
+     * `can={(q) => can(user, q.entity, q.action, q.scope)}`처럼 자기 판정 함수를 꽂는다.
+     * 세션이 없는 편집기 미리보기·스토리북은 `can="allow-all"`을 **명시**한다 —
+     * 아무것도 주지 않으면 게이트는 열리되 console.error가 한 번 난다.
+     *
+     * 이 프롭이 없어서 소비 앱이 `Can`을 자기 구현으로 덮어써야 했다. 이제 렌더러가
+     * `SduiPermissionProvider`로 흘려보내므로 판정 함수만 주면 게이트는 라이브러리 것을 쓴다.
+     * (렌더러 밖에서 직접 provider로 감싸도 동작한다 — 그쪽이 바깥이라 이 프롭이 이긴다.)
+     */
+    can?: SduiCanSetting;
+    onCustomAction?: CustomActionHandler;
+    customValidators?: Record<string, CustomValidator>;
+}
+/**
+ * 서버(JSON 스펙) 주도 페이지 렌더러.
+ * 스펙은 직렬화 가능한 데이터만 담고, 상태·이벤트·폼·내비게이션은 여기서 해석한다.
+ */
+declare function SduiRenderer({ page, registry, adapter, syncUrlState, can, onCustomAction, customValidators, }: SduiRendererProps): React__default.JSX.Element;
+
+/**
+ * 스펙 구조 검증기 — 서버(또는 편집기)가 만든 스펙의 형태 오류를 렌더 전에 찾아낸다.
+ * 렌더러는 개발 모드에서 이 결과를 콘솔에 경고하고, 관리자 편집기는
+ * 저장 전에 같은 검사를 돌려 문제 목록을 보여준다.
+ */
+interface SpecIssue {
+    path: string;
+    message: string;
+}
+declare function validateSpec(page: unknown, knownComponents?: Set<string>): SpecIssue[];
 
 /** Form이 렌더러에 등록하는 검증 설정 */
 interface SduiFormConfig {
@@ -1065,7 +1428,7 @@ declare class NodeErrorBoundary extends React__default.Component<Props, State> {
     static getDerivedStateFromError(error: Error): State;
     componentDidCatch(error: Error): void;
     componentDidUpdate(prevProps: Props): void;
-    render(): string | number | bigint | boolean | React__default.JSX.Element | Iterable<React__default.ReactNode> | Promise<string | number | bigint | boolean | React__default.ReactPortal | React__default.ReactElement<unknown, string | React__default.JSXElementConstructor<any>> | Iterable<React__default.ReactNode> | null | undefined> | null | undefined;
+    render(): string | number | bigint | boolean | Iterable<React__default.ReactNode> | Promise<string | number | bigint | boolean | React__default.ReactPortal | React__default.ReactElement<unknown, string | React__default.JSXElementConstructor<any>> | Iterable<React__default.ReactNode> | null | undefined> | React__default.JSX.Element | null | undefined;
 }
 
-export { Actions, type ActionsProps, Alert, type AlertProps, Badge, type BadgeProps, type BadgeTone, Button, type ButtonProps, Can, type CanProps, Card, type CardProps, type CascadingSearchOption, Checkbox, type CheckboxProps, Col, type CustomActionHandler, type CustomValidator, DatePicker, DateRangePicker, Dialog, type DialogProps, Divider, EmptyState, type EmptyStateProps, Field, type FieldProps, Grid, type GridCardConfig, type GridCardRow, type GridProps, Icon, IconButton, type IconButtonProps, type IconProps, Input, type InputProps, type Justify, type KeyValueItem, KeyValueList, type KeyValueListProps, NodeErrorBoundary, PageHead, type PageHeadProps, Pagination, type PaginationProps, ProgressBar, type ProgressBarProps, RemoteSearchResults, type RemoteSearchResultsProps, ResultTable, type ResultTableColumn, type ResultTableProps, Row, type RowProps, SduiAction, type SduiAdapter, type SduiCanFn, type SduiCanQuery, type SduiCanSetting, SduiDialog, type SduiDispatch, SduiForm, type SduiFormConfig, type SduiFormProps, type SduiGridCard, SduiPage, SduiPermissionProvider, SduiPropValue, type SduiRegistry, SduiRenderer, type SduiRendererProps, SduiRule, type SduiRuntime, type SduiSearchAction, type SduiSearchColumn, SduiSearchDataProvider, SduiSearchResults, type SduiSearchResultsProps, type SearchAction, type SearchColumn, type SearchFetcher, type SearchField, type SearchFilter, type SearchOption, type SearchPage, SearchResults, type SearchResultsProps, type SearchRow, SearchToolbar, type SearchValues, Section, type SectionProps, Select, type SelectOption, type SelectProps, Show, type ShowProps, type SortDir, Spacer, type SpacerProps, type SpecIssue, Spinner, type SpinnerProps, StatCard, type StatCardProps, Switch, type SwitchProps, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextPreset, type TextProps, Textarea, type TextareaProps, Toast, type ToastProps, cascadingValuePaths, cleanSearchValues, createRegistry, defaultAdapter, defaultRegistry, includesLooseSearch, joinMultiValue, normalizeSearchText, searchFieldKeys, searchValuesFromParams, splitMultiValue, useRemoteSearchPage, useSduiCan, useSduiDispatch, useSduiRuntime, useSearchFetcher, validateSpec };
+export { Actions, type ActionsProps, Alert, type AlertProps, Avatar, type AvatarProps, Badge, type BadgeProps, type BadgeTone, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, type ButtonProps, Can, type CanProps, Card, type CardProps, type CascadingSearchOption, Checkbox, type CheckboxProps, Col, type CustomActionHandler, type CustomValidator, DatePicker, DateRangePicker, Dialog, type DialogProps, Divider, EmptyState, type EmptyStateProps, Field, type FieldProps, Grid, type GridCardConfig, type GridCardRow, type GridProps, Icon, IconButton, type IconButtonProps, type IconProps, Input, type InputProps, type Justify, type KeyValueItem, KeyValueList, type KeyValueListProps, type MeterTone, NodeErrorBoundary, PageHead, type PageHeadProps, Pagination, type PaginationProps, ProgressBar, type ProgressBarProps, Radio, type RadioProps, RemoteSearchResults, type RemoteSearchResultsProps, ResultTable, type ResultTableColumn, type ResultTableProps, Row, type RowProps, SduiAction, type SduiAdapter, type SduiAssetContext, type SduiAssetResolver, type SduiBadgeCell, type SduiCanFn, type SduiCanQuery, type SduiCanSetting, type SduiCell, type SduiDateCell, SduiDialog, type SduiDispatch, SduiForm, type SduiFormConfig, type SduiFormProps, type SduiGridCard, type SduiGridCardAction, type SduiGridCardRow, type SduiIconCell, type SduiLinkCell, type SduiNumberCell, SduiPage, SduiPermissionProvider, type SduiProgressCell, SduiPropValue, type SduiRegistry, SduiRenderer, type SduiRendererProps, type SduiRowCondition, SduiRule, type SduiRuntime, type SduiSearchAction, type SduiSearchColumn, SduiSearchDataProvider, SduiSearchResults, type SduiSearchResultsProps, type SduiTagCell, type SduiTextCell, type SearchAction, type SearchColumn, type SearchFetcher, type SearchField, type SearchFilter, type SearchOption, type SearchPage, SearchResults, type SearchResultsProps, type SearchRow, SearchToolbar, type SearchValues, type SearchViewItem, Section, type SectionProps, SegmentedControl, type SegmentedControlProps, type SegmentedItem, Select, type SelectOption, type SelectProps, Show, type ShowProps, SidebarNav, type SidebarNavItem, type SidebarNavProps, type SidebarNavSection, type SortDir, Spacer, type SpacerProps, type SpecIssue, Spinner, type SpinnerProps, StatCard, type StatCardProps, Switch, type SwitchProps, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextPreset, type TextProps, Textarea, type TextareaProps, Toast, type ToastProps, Tooltip, type TooltipProps, cascadingValuePaths, cellRenderer, cleanSearchValues, createRegistry, defaultAdapter, defaultRegistry, includesLooseSearch, joinMultiValue, normalizePageSizes, normalizeSearchText, searchFieldKeys, searchValuesFromParams, splitMultiValue, useRemoteSearchPage, useSduiAssetResolver, useSduiCan, useSduiDispatch, useSduiRuntime, useSduiSandbox, useSearchFetcher, validateSpec };