@wipco/sdui 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -72,12 +72,23 @@ declare function Can({ entity, action, scope, fallback, children }: CanProps): R
  */
 
 interface IconProps extends React__default.SVGAttributes<SVGSVGElement> {
+    /** kebab-case Lucide 이름 — "scan-line", "layers", "circle-alert". */
     name: string;
+    /** 픽셀 박스. 기본 18. */
     size?: number;
+    /** 기본 1.5. 32px 위에서만 2를 쓴다. */
     strokeWidth?: number;
+    /** 주면 role="img" + aria-label. 장식 아이콘은 생략한다. */
+    title?: string;
 }
-/** 스트로크 아이콘. 등록되지 않은 이름은 점으로 대체된다. */
-declare function Icon({ name, size, strokeWidth, ...rest }: IconProps): React__default.JSX.Element;
+/**
+ * 스트로크 아이콘. 130종을 24px 그리드 위에 그린다.
+ *
+ * **등록되지 않은 이름은 `null`이다** — 예전엔 점(●)으로 대체했는데, 그러면 스펙 오타나
+ * 아직 안 넣은 이름이 "없던 자국"으로 화면에 남는다. 빠진 아이콘은 비어 보이는 편이
+ * 낫고, 어차피 잘못된 이름은 check-meta가 팔레트 쪽에서 잡는다.
+ */
+declare function Icon({ name, size, strokeWidth, className, style, title, ...rest }: IconProps): React__default.JSX.Element | null;
 interface ButtonProps extends React__default.ButtonHTMLAttributes<HTMLButtonElement> {
     /** primary = WIPCO Blue, secondary = 외곽선(기본), ghost = 투명, danger = WIPCO Red, link = 인라인 */
     variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | 'link';
@@ -87,33 +98,52 @@ interface ButtonProps extends React__default.ButtonHTMLAttributes<HTMLButtonElem
     icon?: string;
     /** 후행 아이콘 이름 */
     iconEnd?: string;
-    /** 라벨을 스피너로 바꾸고 입력을 막는다 */
+    /**
+     * 라벨을 감추고 스피너를 돌린다.
+     *
+     * 스피너는 **CSS가 그린다**(`.wp-btn--loading::after`) — 엘리먼트를 따로 넣지 않는다.
+     * 예전엔 `<span class="wp-spinner">`를 렌더했는데, 같은 클래스에 ::after 규칙을 가진
+     * 디자인 시스템 스타일시트와 겹치면 원이 두 개 돈다. 그릴 주체를 CSS 한쪽으로 모은다.
+     */
     loading?: boolean;
     block?: boolean;
     disabled?: boolean;
+    /**
+     * 다른 태그로 렌더한다. 링크로 보내야 하는 자리(SSO 이동 등)는 `as="a"` + `href`다 —
+     * `<button>`에 href를 달면 아무 데도 가지 않는다.
+     *
+     * button이 아닐 때는 `disabled` 속성이 없으므로 비활성은 `aria-disabled`로만 알린다
+     * (그래서 button일 때도 둘 다 붙인다 — 표기가 태그에 따라 달라지지 않게).
+     */
+    as?: 'button' | 'a' | 'span';
     children?: React__default.ReactNode;
 }
-declare function Button({ variant, size, icon, iconEnd, loading, block, disabled, children, className, type, ...rest }: ButtonProps): React__default.JSX.Element;
+declare function Button({ variant, size, icon, iconEnd, loading, block, disabled, as, children, className, ...rest }: ButtonProps): React__default.JSX.Element;
 interface IconButtonProps extends React__default.ButtonHTMLAttributes<HTMLButtonElement> {
     icon: string;
-    /** 접근성 라벨(필수 권장) */
+    /** 접근성 라벨(필수 권장) — title이자 aria-label이 된다. */
     label?: string;
-    size?: 'xs' | 'sm' | 'md';
+    /** xs 24 · sm 28 · md 32(기본) · lg 40 px 정사각 */
+    size?: 'xs' | 'sm' | 'md' | 'lg';
     /**
      * 예전 이름. `variant`를 주지 않았을 때만 쓰인다 — `variant` 주석 참고.
      * @deprecated `variant`로 옮겨라. `tone="danger"`는 `variant="danger"`와 같다.
      */
     tone?: 'default' | 'danger';
     /**
-     * 디자인 시스템 어휘. ghost = 투명(기본) · outlined = 하드라인 테두리 · danger = 빨강.
+     * 디자인 시스템 어휘. ghost = 투명(기본) · outlined = 하드라인 테두리 ·
+     * solid = 채움 · danger = 빨강 · onchrome = 네이비 사이드바/탑바 위.
      *
      * 같은 자리를 가리키는 프롭이 `tone`과 둘로 갈라져 있는데 **variant가 이긴다** —
      * 스펙과 디자인 시스템 문서가 쓰는 이름이 이쪽이고, 값 어휘도 넓다(outlined는 tone에 없다).
      * variant를 주지 않으면 tone이 그대로 먹으므로 tone만 쓰던 코드는 그대로 돈다.
      */
-    variant?: 'ghost' | 'outlined' | 'danger';
+    variant?: 'ghost' | 'outlined' | 'solid' | 'danger' | 'onchrome';
+    /** 토글 상태 — aria-pressed로 나가고 선택 틴트를 입는다. */
+    pressed?: boolean;
+    disabled?: boolean;
 }
-declare function IconButton({ icon, label, size, tone, variant, className, type, ...rest }: IconButtonProps): React__default.JSX.Element;
+declare function IconButton({ icon, label, size, tone, variant, pressed, disabled, className, type, ...rest }: IconButtonProps): React__default.JSX.Element;
 interface InputProps extends Omit<React__default.InputHTMLAttributes<HTMLInputElement>, 'size'> {
     /** sm 28 · md 32(기본) · lg 40 px */
     size?: 'sm' | 'md' | 'lg';
@@ -124,15 +154,11 @@ interface InputProps extends Omit<React__default.InputHTMLAttributes<HTMLInputEl
     /** 고정폭 글꼴 — ID, 좌표, 해시 */
     mono?: boolean;
     /**
-     * 입력 오른쪽 끝에 겹쳐 그리는 후행 표시 — "원", "위", "mm" 같은 단위가 대부분이다.
-     *
-     * 단위를 값 안에 섞어 넣지 않는다는 규칙을 지키려면 값이 아니라 입력 위에 얹어야 해서,
-     * 선행 `icon`과 같은 래퍼를 쓴다.
+     * 입력 오른쪽 끝에 겹쳐 그리는 후행 표시.
      *
-     * 문자열은 **ICON_PATHS에 있는 이름이면 아이콘, 아니면 그대로 단위 글자**로 그린다.
-     * 디자인 시스템 쪽 용례는 `trailing="eye"`(비밀번호 보기)처럼 아이콘 이름인데
-     * 실제 스펙 9곳은 전부 "원"·"위" 같은 단위 글자라, 둘 중 하나만 고르면 나머지가 깨진다.
-     * 단위가 아이콘 이름과 겹치는 일은 없으므로 이름으로 갈라도 안전하다.
+     * **문자열은 아이콘 이름으로 읽는다** — `trailing="eye"`(비밀번호 보기)가 원래 용례다.
+     * 등록되지 않은 이름이면 Icon이 null을 내므로 자리만 남는다. 단위 글자("원", "mm")를
+     * 넣고 싶으면 문자열이 아니라 노드로 줘라: `trailing={<span>원</span>}`.
      */
     trailing?: React__default.ReactNode;
 }
@@ -158,9 +184,16 @@ declare function Select({ options, size, invalid, placeholder, className, ...res
 interface CheckboxProps extends React__default.InputHTMLAttributes<HTMLInputElement> {
     label?: React__default.ReactNode;
     description?: React__default.ReactNode;
+    /**
+     * 부분 선택 — 전체선택 체크박스의 "일부만 골랐다" 상태.
+     *
+     * HTML 속성이 아니라 DOM 프로퍼티라 ref로 직접 넣어야 한다(마크업에 남지 않는다).
+     * 글리프도 체크가 아니라 빼기로 바뀐다.
+     */
+    indeterminate?: boolean;
     disabled?: boolean;
 }
-declare function Checkbox({ label, description, disabled, className, ...rest }: CheckboxProps): React__default.JSX.Element;
+declare function Checkbox({ label, description, indeterminate, disabled, className, ...rest }: CheckboxProps): React__default.JSX.Element;
 interface SwitchProps extends Omit<React__default.InputHTMLAttributes<HTMLInputElement>, 'size'> {
     label?: React__default.ReactNode;
     size?: 'sm' | 'md';
@@ -230,10 +263,12 @@ interface ToastProps extends Omit<React__default.HTMLAttributes<HTMLDivElement>,
     tone?: 'info' | 'success' | 'warning' | 'danger';
     title?: React__default.ReactNode;
     children?: React__default.ReactNode;
+    /** 인라인 액션 하나 — 되돌리기 같은 것. Button variant="link"를 넣는다. */
+    action?: React__default.ReactNode;
     onClose?: () => void;
 }
 /** 우하단 일시 알림. .wp-toast-region 안에 렌더링된다. */
-declare function Toast({ tone, title, children, onClose, className, ...rest }: ToastProps): React__default.JSX.Element;
+declare function Toast({ tone, title, children, action, onClose, className, ...rest }: ToastProps): React__default.JSX.Element;
 interface TabItem {
     value: string;
     label: React__default.ReactNode;
@@ -245,8 +280,10 @@ interface TabsProps extends Omit<React__default.HTMLAttributes<HTMLDivElement>,
     value: string;
     onChange?: (value: string) => void;
     size?: 'md' | 'lg';
+    /** 네이비 탑바 위 — 밝은 글자, 빨간 인디케이터. */
+    onChrome?: boolean;
 }
-declare function Tabs({ items, value, onChange, size, className, ...rest }: TabsProps): React__default.JSX.Element;
+declare function Tabs({ items, value, onChange, size, onChrome, className, ...rest }: TabsProps): React__default.JSX.Element;
 interface TableColumn {
     key: string;
     header: React__default.ReactNode;
@@ -255,6 +292,8 @@ interface TableColumn {
     align?: 'left' | 'right';
     mono?: boolean;
     strong?: boolean;
+    /** 헤더를 정렬 버튼으로 만든다. 실제 정렬은 `sort`·`onSort`가 담당한다. */
+    sortable?: boolean;
     /**
      * 셀 값을 Badge로 렌더링 — JSON 스펙에서 쓸 수 있는 선언적 지정.
      * toneMap: 값 → tone, labelMap: 값 → 표시 텍스트(생략 시 값 그대로)
@@ -272,13 +311,24 @@ interface TableProps extends React__default.TableHTMLAttributes<HTMLTableElement
     /** 40px 대신 32px 행 */
     dense?: boolean;
     hover?: boolean;
+    /** 스크롤 본문용 고정 헤더 */
+    sticky?: boolean;
+    /** 현재 정렬 상태 — 해당 컬럼 헤더의 화살표 방향을 정한다 */
+    sort?: {
+        key: string;
+        dir: 'asc' | 'desc';
+    };
+    /** 정렬 헤더를 눌렀을 때. 주지 않으면 sortable 컬럼도 버튼이 되지 않는다 */
+    onSort?: (key: string) => void;
+    /** 선택된 행의 rowKey 값 — 해당 행에 aria-selected가 붙고 하이라이트된다 */
+    selectedIds?: any[];
     /** 행 key와 선택에 쓸 필드. 기본 "id" */
     rowKey?: string;
     onRowClick?: (row: any) => void;
     /** rows가 비었을 때 대신 렌더링 — EmptyState 권장 */
     empty?: React__default.ReactNode;
 }
-declare function Table({ columns, rows, dense, hover, rowKey, onRowClick, empty, className, ...rest }: TableProps): React__default.JSX.Element;
+declare function Table({ columns, rows, dense, hover, sticky, sort, onSort, selectedIds, rowKey, onRowClick, empty, className, ...rest }: TableProps): React__default.JSX.Element;
 interface StatCardProps extends React__default.HTMLAttributes<HTMLDivElement> {
     label: React__default.ReactNode;
     value: React__default.ReactNode;
@@ -302,24 +352,33 @@ interface EmptyStateProps extends Omit<React__default.HTMLAttributes<HTMLDivElem
 declare function EmptyState({ icon, title, children, actions, tight, className, ...rest }: EmptyStateProps): React__default.JSX.Element;
 interface SpinnerProps extends React__default.HTMLAttributes<HTMLSpanElement> {
     size?: 'sm' | 'md' | 'lg';
+    /** 네이비/뷰어 표면 위 — 밝은 테두리로 뒤집는다. */
+    inverse?: boolean;
     label?: string;
 }
-declare function Spinner({ size, label, className, ...rest }: SpinnerProps): React__default.JSX.Element;
+declare function Spinner({ size, inverse, label, className, ...rest }: SpinnerProps): React__default.JSX.Element;
 interface ProgressBarProps extends React__default.HTMLAttributes<HTMLDivElement> {
-    /** 0~100 */
+    /** 0~`max` */
     value: number;
+    /** 기본 100. 용량 게이지처럼 분모가 100이 아닌 자리에 쓴다 */
+    max?: number;
     /** danger 임계 강조 등 */
     tone?: 'brand' | 'success' | 'warning' | 'danger' | 'info';
+    /** sm 4 · md 6(기본) · lg 8 px */
+    size?: 'sm' | 'md' | 'lg';
+    /** 사선 해치 애니메이션 — 진행 중인 작업에만 */
+    striped?: boolean;
     label?: React__default.ReactNode;
     /**
-     * 라벨 줄 오른쪽 끝에 현재 값을 퍼센트로 적는다.
+     * 현재 값을 퍼센트로 적는다.
      *
      * 막대만으로는 82%와 91%를 구분할 수 없어서, 여러 개를 세로로 쌓아 비교하는
-     * 자리(공정별 진척 목록 등)에서 필요하다. 라벨 없이 켜도 값은 오른쪽에 붙는다.
+     * 자리(공정별 진척 목록 등)에서 필요하다. 라벨이 있으면 라벨 줄 오른쪽 끝에,
+     * 라벨이 없으면 막대 오른쪽 옆(.wp-meter-row)에 붙는다.
      */
     showValue?: boolean;
 }
-declare function ProgressBar({ value, tone, label, showValue, className, ...rest }: ProgressBarProps): React__default.JSX.Element;
+declare function ProgressBar({ value, max, tone, size, striped, showValue, label, className, ...rest }: ProgressBarProps): React__default.JSX.Element;
 interface PaginationProps extends Omit<React__default.HTMLAttributes<HTMLDivElement>, 'onChange'> {
     page: number;
     pageCount: number;
@@ -343,6 +402,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 프리셋 */
@@ -441,6 +596,10 @@ declare function Divider({ style }: {
     style?: React__default.CSSProperties;
 }): React__default.JSX.Element;
 
+/** SduiRenderer가 제공하는 액션 디스패처. 레지스트리의 복합 컴포넌트가 선언적 액션을 실행할 때 쓴다. */
+type SduiDispatch = (action: SduiAction, eventValue?: unknown) => void;
+declare function useSduiDispatch(): SduiDispatch;
+
 /**
  * 목록 원격 조회 어댑터.
  *
@@ -602,6 +761,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);
@@ -631,6 +804,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;
@@ -654,9 +835,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만으로 검색+목록 화면을 구성한다.
@@ -677,12 +945,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;
@@ -691,10 +983,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;
@@ -713,6 +1009,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;
@@ -726,7 +1029,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/필드키 쿼리를 붙여 조회하고
@@ -736,7 +1039,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`은 정렬 헤더·선택 표시·가상 스크롤을
@@ -891,42 +1194,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[];
-
 /**
  * 권한 판정 주입 지점.
  *
@@ -968,9 +1235,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 {
@@ -1009,4 +1321,4 @@ declare class NodeErrorBoundary extends React__default.Component<Props, State> {
     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;
 }
 
-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 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, useSduiCan, useSduiDispatch, useSduiRuntime, useSearchFetcher, validateSpec };