sellmate-design-system-react 9.0.0-beta.11 → 9.0.0-beta.112

package/dist/lib/floating-height.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Radix Floating Content 를 창 높이 안에 가두기 위한 헬퍼 — floating-width.ts 의 높이 버전.
+ *
+ * Radix 는 충돌이 나면 위치만 밀 뿐(shift) 높이는 줄이지 않는다 — 콘텐츠가 창보다 높으면
+ * 밀려난 자리에서 그대로 화면 밖으로 삐져나간다. 실제로 줄이려면 size 미들웨어가 계산해
+ * 두는 available-height 를 상한으로 직접 걸어야 한다.
+ */
+/** Radix Popover 계열(SPortal·SSelect·SChipInput·SPopover·STooltip 등)이 노출하는 가용 높이. */
+export declare const POPOVER_AVAILABLE_HEIGHT = "var(--radix-popover-content-available-height)";
+/** Radix DropdownMenu 계열(SDropdownButton)이 노출하는 가용 높이. */
+export declare const DROPDOWN_AVAILABLE_HEIGHT = "var(--radix-dropdown-menu-content-available-height)";
+/**
+ * 높이 제약을 가용 높이 안으로 가둔다. 값이 없으면 가용 높이 자체가 상한이 된다.
+ */
+export declare function clampToAvailableHeight(value: string | number | undefined, availableHeight: string): string;

package/dist/lib/floating-width.d.ts

@@ -6,8 +6,7 @@
  * 두는 available-width 를 상한으로 직접 걸어야 한다.
  *
  * available-width 는 shift 가 켜진 축에서 `창 폭 - collisionPadding*2` 로 잡히므로,
- * 팝업이 어디로 밀렸든 값이 흔들리지 않는다(= sd-portal 이 `innerWidth - viewportPadding*2`
- * 로 계산하던 것과 같은 값).
+ * 팝업이 어디로 밀렸든 값이 흔들리지 않는다.
  */
 /** Radix Popover 계열(SPortal·SSelect·SChipInput·SPopover·STooltip 등)이 노출하는 가용 폭. */
 export declare const POPOVER_AVAILABLE_WIDTH = "var(--radix-popover-content-available-width)";

package/dist/lib/form.d.ts

@@ -1,7 +1,10 @@
-/** 유효성 규칙: 유효하면 true, 아니면 에러 메시지 문자열 반환 (sd types/form Rule 포팅) */
+/** 유효성 규칙: 유효하면 true, 아니면 에러 메시지 문자열 반환 */
 export type Rule = (value: unknown) => true | string;
-/** rules를 순서대로 실행해 첫 실패 메시지를 반환. 모두 통과하면 "" */
-export declare function runRules(value: unknown, rules?: Rule[]): string;
+/** rules를 순서대로 실행해 첫 실패 메시지를 반환. 모두 통과하면 "".
+ *  rule 이 문구 없이 `false` 를 돌려줄 때는 `invalidMessage` 를 쓴다 — 컴포넌트는 로케일을 아는 `useRunRules` 로 부른다 */
+export declare function runRules(value: unknown, rules?: Rule[], invalidMessage?: string): string;
+/** `runRules` 에 현재 로케일의 기본 오류 문구를 묶어 돌려주는 훅 — 로케일이 바뀔 때만 함수가 바뀐다 */
+export declare function useRunRules(): (value: unknown, rules?: Rule[]) => string;
 /** SForm에 등록되는 필드 항목 */
 export interface FormFieldEntry {
     /** 폼 연동용 name (validationError names·focus 대상 식별) */

package/dist/lib/global-overlay.d.ts

@@ -13,5 +13,10 @@ export declare const globalOverlayProps: {
 /**
  * Radix 의 outside 이벤트(pointerDownOutside/focusOutside/interactOutside)가
  * 전역 레이어에서 비롯됐는지 판별한다. Radix 는 원본 이벤트를 `detail.originalEvent` 에 담는다.
+ *
+ * 요소인지는 `instanceof` 가 아니라 `nodeType` 으로 본다. `instanceof` 는 그 realm 의 전역
+ * 생성자와 견주는 것이라 두 곳에서 어긋난다 — `Element` 가 전역에 없는 환경(테스트 DOM)에서는
+ * 그대로 터지고, iframe 처럼 realm 이 다른 문서에서 온 요소는 거짓이 되어 가드가 조용히
+ * 빗나간다. `nodeType` 은 어느 realm 의 노드에도 같은 값으로 있다.
  */
 export declare function isFromGlobalOverlay(event: Event): boolean;

package/dist/lib/grid-key-nav.d.ts

@@ -0,0 +1,10 @@
+import type { KeyboardEvent } from 'react';
+/** 수직 이동 대상 열을 표시하는 속성. 입력이 아니라 입력을 담은 셀(`<td>` 등)에 단다. */
+export declare const GRID_NAV_ATTR = "data-grid-nav";
+/**
+ * Enter / Shift+Enter 를 같은 열의 아래/위 행 입력으로의 포커스 이동으로 바꾼다.
+ * 이동을 켠 열(`data-grid-nav` 가 달린 셀)의 `<input>` 에서만 동작하고, 그 외 필드의
+ * Enter(폼 제출·textarea 줄바꿈·열린 드롭다운 선택)는 건드리지 않는다.
+ * 화면에 그려진 행 사이만 이동하고, 더 갈 곳이 없으면 이동 없이 Enter 만 막는다.
+ */
+export declare function handleGridKeyNav(e: KeyboardEvent<HTMLElement>): void;

package/dist/lib/hover-preview.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 호버 미리보기(`SImage previewOnHover`)가 뜨는 자리를 계산한다.
+ *
+ * **시작점은 썸네일의 한가운데**다 — 미리보기의 좌상단 모서리가 썸네일 중앙에 놓인다.
+ * 그래서 미리보기는 늘 오른쪽 아래로 펼쳐지고, 원래 보던 썸네일을 가리지 않는다.
+ *
+ * 창 오른쪽·아래로 넘치면 **넘친 만큼만 왼쪽·위로 되민다**. 반대편으로 뒤집지 않는다 —
+ * 뒤집으면 커서와 미리보기의 관계가 순간 바뀌어 어느 썸네일의 미리보기인지 읽기 어렵다.
+ * (Radix 의 `avoidCollisions` 는 shift 와 flip 을 함께 켜므로 쓰지 않고, 이 계산으로 대신한다.)
+ */
+/** 위치 계산에 필요한 만큼만 추린 사각형 — DOMRect 을 그대로 받을 수 있다 */
+export interface HoverPreviewAnchorRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface HoverPreviewOriginInput {
+    /** 썸네일의 viewport 기준 사각형 */
+    anchor: HoverPreviewAnchorRect;
+    /** 미리보기 상자의 한 변(px). 정사각형이다 */
+    size: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    /** 창 가장자리와 띄울 최소 간격 */
+    padding?: number;
+}
+/** 미리보기 상자의 좌상단 좌표 (viewport 기준) */
+export declare function hoverPreviewOrigin({ anchor, size, viewportWidth, viewportHeight, padding, }: HoverPreviewOriginInput): {
+    x: number;
+    y: number;
+};

package/dist/lib/inert.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 접힌 영역을 tab 순서에서 빼는 ref.
+ *
+ * 접기·펴기를 `grid-template-rows` 로 애니메이션하는 영역은 접힌 뒤에도 DOM 에 남는다.
+ * `aria-hidden` 은 스크린리더에서만 지우므로, 그것만으로는 Tab 이 보이지 않는 체크박스·버튼에
+ * 계속 멈춘다. `inert` 는 그 안쪽 전체를 포커스·포인터 대상에서 빼며 자손까지 함께 적용된다.
+ *
+ * JSX 의 `inert` prop 은 React 19 부터라, peer 가 `>=18` 인 이 패키지에서는 DOM 속성으로 직접
+ * 넣는다. 브라우저는 속성이 붙어 있는지만 보므로 값은 상관없다.
+ */
+export declare function useInertRef<T extends HTMLElement>(inert: boolean): import("react").RefObject<T | null>;

package/dist/lib/list-box-item.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 드롭다운 목록 행(SSelect · SChipFilter · SChipInput 의 리스트박스 항목)이 함께 쓰는 여백.
+ * 스펙(`--cmp-listBoxItem-*`)이 하나라 한곳에 둔다. 행 모양 자체는 아직 컴포넌트마다 따로 그린다.
+ */
+/** 항목 좌측 패딩 — depth1(그룹 헤더·비계층 항목) / depth2 / depth3 */
+export declare const LIST_BOX_ITEM_PADDING_LEFT: {
+    readonly 1: "var(--cmp-listBoxItem-paddingLeft-depth1)";
+    readonly 2: "var(--cmp-listBoxItem-paddingLeft-depth2)";
+    readonly 3: "var(--cmp-listBoxItem-paddingLeft-depth3)";
+};
+/** 항목 상하·우측 패딩 — 모든 depth 에서 같다 */
+export declare const LIST_BOX_ITEM_PADDING_Y_RIGHT: {
+    readonly paddingTop: "var(--cmp-listBoxItem-paddingY)";
+    readonly paddingBottom: "var(--cmp-listBoxItem-paddingY)";
+    readonly paddingRight: "var(--cmp-listBoxItem-paddingRight)";
+};

package/dist/lib/locale-context.d.ts

@@ -0,0 +1,26 @@
+import { type ReactNode } from 'react';
+import { type SLocale, type SLocaleMessages, type SLocaleMessagesOverride } from './locale';
+interface LocaleValue {
+    locale: SLocale;
+    messages: SLocaleMessages;
+    /** 로케일에 맞춘 숫자 포맷(천 단위 구분). 날짜 형식은 고정이라 여기서 다루지 않는다 */
+    formatNumber: (value: number) => string;
+}
+export interface SLocaleProviderProps {
+    /** `ko` | `en` | `ja` | `zh` (`en-US` 처럼 지역이 붙어도 된다). 모르는 값이면 `ko` 로 폴백한다 */
+    locale?: string;
+    /**
+     * 일부 문구만 덮어쓸 때. 그룹 단위로 얕게 병합되고, 값이 `undefined` 인 키는 무시한다.
+     * 렌더마다 새 객체를 만들면 하위 컴포넌트가 매번 다시 그려지므로 모듈 상수나 `useMemo` 로 안정시킨다.
+     */
+    messages?: SLocaleMessagesOverride;
+    children?: ReactNode;
+}
+/**
+ * SLocaleProvider — 컴포넌트 내장 문구의 로케일을 정한다. 앱 루트에 한 번 둔다.
+ * `SModalOutlet` 은 이 Provider 안쪽에 렌더해야 명령형 모달도 같은 로케일을 상속한다.
+ */
+export declare function SLocaleProvider({ locale, messages, children }: SLocaleProviderProps): import("react").JSX.Element;
+/** 현재 로케일·메시지·숫자 포맷터를 반환한다. Provider 밖이면 `ko` 기본값이다 */
+export declare function useLocale(): LocaleValue;
+export {};

package/dist/lib/locale.d.ts

@@ -0,0 +1,320 @@
+/**
+ * 컴포넌트 내장 문구(i18n)의 메시지 타입·번들·해석 로직.
+ *
+ * 외부 i18n 라이브러리 없이 타입 안전한 객체로 둔다. 어순·조사가 얽힌 문구는 문자열이
+ * 아니라 함수로 정의한다(예: `(n) => '외 ' + n + '개'`). React 에 의존하지 않는 순수 모듈이라
+ * Node 에서 그대로 테스트한다.
+ *
+ * 날짜 형식(YYYY-MM-DD)은 로케일과 무관하게 고정이고, 숫자 구분만 로케일을 따른다.
+ */
+export declare const SLOCALES: readonly ["ko", "en", "ja", "zh"];
+export type SLocale = (typeof SLOCALES)[number];
+/** 기본 로케일 — Provider 가 없거나 모르는 로케일이면 이 값으로 폴백한다 */
+export declare const DEFAULT_LOCALE: SLocale;
+/** 받침 유무에 따라 "을/를" 등 조사를 고른다. 한글이 아니면(영문 등) consonant 형을 기본으로 쓴다 */
+export declare const koreanParticle: (word: string, consonant: string, vowel: string) => string;
+export interface SLocaleMessages {
+    /** 여러 컴포넌트가 함께 쓰는 짧은 문구(버튼 라벨·aria-label) */
+    common: {
+        close: string;
+        clear: string;
+        confirm: string;
+        all: string;
+        back: string;
+        more: string;
+        moreActions: string;
+        openMenu: string;
+        dragHandle: string;
+        resizeDrawer: string;
+        search: string;
+        /** 개수 뒤에 붙는 단위 — `3개` */
+        count: (n: number) => string;
+    };
+    numberInput: {
+        /** 범위 안내 — 값은 천 단위 구분이 들어간 문자열로 온다 */
+        rangeBetween: (min: string, max: string) => string;
+        atLeast: (min: string) => string;
+        atMost: (max: string) => string;
+        increase: string;
+        decrease: string;
+    };
+    chipInput: {
+        /** 구분자에 콤마가 있을 때의 기본 안내 */
+        placeholderWithComma: string;
+        placeholder: string;
+        /** `duplicateLabel` 을 준 경우 — 어순이 언어마다 달라 함수로 둔다 */
+        duplicateNamed: (label: string) => string;
+        duplicate: string;
+        maxCount: (max: number) => string;
+    };
+    slider: {
+        minValue: string;
+        maxValue: string;
+    };
+    /** 채팅 컴포넌트(SChatInput·SChatMessage·SChatAttachedFile)의 문구 */
+    chat: {
+        removeAttachment: (name: string) => string;
+        placeholder: string;
+        attachFile: string;
+        stopResponse: string;
+        send: string;
+        read: string;
+        unread: string;
+    };
+    loadingModal: {
+        loadingMessage: string;
+        errorMessage: string;
+        errorButton: string;
+        ariaTitle: string;
+    };
+    stepper: {
+        errorTooltip: string;
+        ariaLabel: string;
+    };
+    timeline: {
+        empty: string;
+    };
+    callout: {
+        dangerTitle: string;
+    };
+    guide: {
+        tip: string;
+        notion: string;
+    };
+    loginCard: {
+        login: string;
+    };
+    modal: {
+        defaultTitle: string;
+    };
+    launcher: {
+        opensInNewTab: string;
+    };
+    chipFilter: {
+        periodDay: string;
+        periodMonth: string;
+        periodQuarter: string;
+        periodHalf: string;
+        periodYear: string;
+        custom: string;
+        today: string;
+        last7: string;
+        last30: string;
+        /** 프리셋 라벨에 이미 최대 일수를 적었는지 가리는 단어 — 있으면 `maxRangeHint` 를 또 덧붙이지 않는다 */
+        maxWord: string;
+        maxRangeHint: (days: number) => string;
+        requireAll: string;
+        requireAnyDefault: string;
+        /** 조사(을/를)가 얽혀 함수로 둔다 */
+        requireAnyNamed: (name: string) => string;
+        requireField: (label: string) => string;
+        fieldFallback: string;
+        /** 값이 여럿일 때 첫 값 뒤에 붙는 요약 — `rest` 는 첫 값을 뺀 나머지 개수 */
+        valueListMore: (first: string, rest: number) => string;
+        quarter: (n: number) => string;
+        firstHalf: string;
+        secondHalf: string;
+        removeFilter: (label: string) => string;
+        clearFilter: (label: string) => string;
+        resetSearch: string;
+        addFilter: string;
+        noAddableFilter: string;
+        selectNone: string;
+        selectAll: string;
+        removeItem: (label: string) => string;
+        keywordContains: string;
+        keywordExact: string;
+        keywordExcludes: string;
+        keywordHintCsv: string;
+        keywordHintEnter: string;
+        /** 키워드 검색조건 라디오 앞 라벨 */
+        keywordCondition: string;
+        noSearchResults: string;
+    };
+    chart: {
+        unit: (unit: string) => string;
+        pie: string;
+        donut: string;
+        /** 원형 계열 그래프의 aria-label — `kind` 는 `pie`·`donut` 문구가 온다 */
+        radialSummary: (count: number, kind: string) => string;
+        barSummary: (categories: number, series: number, stacked: boolean) => string;
+        lineSummary: (categories: number, series: number, stacked: boolean) => string;
+    };
+    /** 날짜·시간 컴포넌트의 라벨. 날짜 값의 형식(YYYY-MM-DD)은 로케일과 무관하게 고정이다 */
+    date: {
+        /** 일요일부터 시작하는 짧은 요일 */
+        weekdays: readonly string[];
+        /** 일요일부터 시작하는 긴 요일 — `withWeekday` 가 날짜 뒤에 붙인다 */
+        weekdaysLong: readonly string[];
+        today: string;
+        prevYear: string;
+        nextYear: string;
+        prevMonth: string;
+        nextMonth: string;
+        monthLabel: (month: number) => string;
+        dayLabel: (day: number) => string;
+        /** 날짜 입력 칸 뒤에 붙는 단위. 영어는 YYYY-MM-DD 모양을 따라 구분 기호를 쓴다 */
+        unitYear: string;
+        unitMonth: string;
+        unitDay: string;
+        hourItem: (hour: string) => string;
+        minuteItem: (minute: string) => string;
+        /** 시·분·오전/오후 목록의 접근성 이름 — `prefix` 는 "시작" 같은 앞말이고 없으면 빈 문자열이다 */
+        hourAria: (prefix: string) => string;
+        minuteAria: (prefix: string) => string;
+        meridiemAria: (prefix: string) => string;
+        am: string;
+        pm: string;
+        rangeFrom: string;
+        rangeTo: string;
+        clearDate: string;
+        clearMonth: string;
+        clearYear: string;
+        clearPeriod: string;
+        clearTime: string;
+        clearTimeRange: string;
+        start: string;
+        end: string;
+        startTime: string;
+        endTime: string;
+    };
+    form: {
+        invalid: string;
+    };
+    accountListBox: {
+        accountSetting: string;
+        language: string;
+        logout: string;
+    };
+    gnbSystem: {
+        alert: string;
+        setting: string;
+    };
+    /** SEditor 툴바·본문의 문구 */
+    editor: {
+        placeholder: string;
+        toolbarLabel: string;
+        tableSize: string;
+        linkUrl: string;
+        apply: string;
+        remove: string;
+        headingLevel: string;
+        headingBody: string;
+        fontSize: string;
+        fontSizeDefaultLabel: string;
+        bold: string;
+        italic: string;
+        underline: string;
+        strike: string;
+        inlineCode: string;
+        textColor: string;
+        clearColor: string;
+        alignLeft: string;
+        alignCenter: string;
+        alignRight: string;
+        alignJustify: string;
+        bulletList: string;
+        orderedList: string;
+        taskList: string;
+        list: string;
+        blockquote: string;
+        codeBlock: string;
+        divider: string;
+        link: string;
+        insertImage: string;
+        image: string;
+        table: string;
+        addRowAbove: string;
+        addRowBelow: string;
+        addColLeft: string;
+        addColRight: string;
+        mergeCells: string;
+        splitCell: string;
+        toggleHeaderRow: string;
+        toggleHeaderCol: string;
+        deleteRow: string;
+        deleteCol: string;
+        deleteTable: string;
+        undo: string;
+        redo: string;
+        colorDefault: string;
+        colorSecondary: string;
+        colorMuted: string;
+        colorAccent: string;
+        colorBrand: string;
+        colorSuccess: string;
+        colorWarning: string;
+        colorDanger: string;
+        tableCell: (r: number, c: number) => string;
+        tableSizeText: (rows: number, cols: number) => string;
+        heading: (level: number) => string;
+        fontSizeDefault: (px: number) => string;
+        closeEditing: (label: string) => string;
+    };
+    /** 입력 컴포넌트(SInput·STextarea·SSearchInput·SBarcodeInput·SChipInput)의 기본 문구 */
+    input: {
+        placeholder: string;
+        searchWithinResults: string;
+        clearInput: string;
+        showPassword: string;
+    };
+    pagination: {
+        firstPage: string;
+        prevPage: string;
+        nextPage: string;
+        lastPage: string;
+        prevGroup: string;
+        nextGroup: string;
+    };
+    select: {
+        placeholder: string;
+        allSelected: string;
+        /** 선택값 전체 지우기 버튼 aria-label */
+        clear: string;
+        /** 칩 × 버튼 aria-label — 어순이 언어마다 달라 함수로 둔다 */
+        deselect: (label: string) => string;
+        searchPlaceholder: string;
+        empty: string;
+        loading: string;
+    };
+    table: {
+        /** 헤더 전체 선택 체크박스 aria-label */
+        selectAll: string;
+        /** 행 선택 체크박스 aria-label 기본값 — `rowSelectLabel` 이 우선한다 */
+        selectRow: string;
+        empty: string;
+        /** 페이지당 행 수 기본 옵션 라벨 */
+        rowsPerPage: (count: number) => string;
+        editable: string;
+        opensInNewScreen: string;
+        /** 정렬 버튼 aria-label — 어순이 언어마다 달라 함수로 둔다 */
+        sortBy: (label: string) => string;
+        /** 좁게 보고 있을 때 누르면 넓어지는 토글 라벨 */
+        denseOff: string;
+        /** 넓게 보고 있을 때 누르면 좁아지는 토글 라벨 */
+        denseOn: string;
+    };
+    /**
+     * 건수 요약은 숫자만 강조색 `<b>` 로 감싸므로 숫자 앞뒤 문구를 나눠 둔다
+     * (`before` + 숫자 + `after`). 어순이 달라도 숫자 위치만 정하면 된다.
+     * 숫자와 문구 사이 공백도 문구 값에 들어 있다 — override 할 때 공백까지 함께 적는다.
+     */
+    tableBar: {
+        totalBefore: string;
+        totalAfter: string;
+        selectedBefore: string;
+        selectedAfter: string;
+    };
+}
+/** 소비 앱이 일부 문구만 덮어쓸 때 쓰는 부분 메시지 */
+export type SLocaleMessagesOverride = {
+    [K in keyof SLocaleMessages]?: Partial<SLocaleMessages[K]>;
+};
+/**
+ * 로케일 문자열을 지원 로케일로 정규화한다. `en-US`·`ja_JP` 처럼 지역이 붙어도 언어 코드로 맞추고,
+ * 모르는 값이거나 비어 있으면 기본 로케일(ko)로 폴백한다 — 예외로 화면을 깨지 않는다.
+ * `zh` 는 간체 문구라 `zh-TW`·`zh-HK` 도 같은 번들로 연결된다(번체 번들은 아직 없다 — 필요하면 `messages` 로 덮어쓴다).
+ */
+export declare function normalizeLocale(locale: string | undefined | null): SLocale;
+/** 이미 정규화된 로케일의 번들 위에 소비 앱의 부분 override 를 그룹 단위로 얹어 최종 메시지를 만든다 */
+export declare function resolveMessages(locale: string | undefined | null, override?: SLocaleMessagesOverride): SLocaleMessages;

package/dist/lib/mode-listbox.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 연·월·시간을 세로 리스트에서 고르는 피커 조각(SDatePicker 의 연·월 리스트, STimePicker 의 시간
+ * 리스트)이 함께 쓰는 치수와 항목 클래스. 스펙(`--cmp-datepicker-mode-*`)이 하나라 한곳에 둔다.
+ */
+/** 리스트 높이(px) — 항목 높이와 함께 "선택 항목을 가운데로" 계산에 쓴다 */
+export declare const MODE_LIST_HEIGHT = 240;
+/** 항목 한 줄 높이(px) — paddingY(4) × 2 + line-height(20) */
+export declare const MODE_ITEM_HEIGHT = 28;
+/** 리스트 항목(button) 클래스 — 기본 / 선택 / 비활성 */
+export declare const modeListItemClass: (selected: boolean, disabled: boolean) => string;

package/dist/lib/overlay-scrollbar.d.ts

@@ -0,0 +1,32 @@
+import { type RefObject } from 'react';
+/**
+ * 오버레이 스크롤바 — 스크롤 요소 **위에** 얹는 막대.
+ *
+ * 네이티브 스크롤바는 레이아웃 폭을 실제로 차지해서, 스크롤이 생기는 순간 안쪽 콘텐츠
+ * 폭이 그만큼 줄어든다. 표처럼 폭이 고정된 것이 들어 있으면 그 한 번의 흔들림이 그대로
+ * 보인다. 그래서 네이티브 막대를 숨기고(`SCROLLBAR_HIDDEN_CLASS`) 같은 자리에 그림만
+ * 얹는다 — 자리를 차지하지 않으므로 콘텐츠 폭이 변하지 않는다.
+ *
+ * **부모가 `relative` 여야 한다.** 막대는 그 상자를 기준으로 절대 배치된다.
+ */
+/** 막대가 도는 트랙의 폭(px). 세로·가로 막대가 만나는 모서리를 비우는 데도 쓴다. */
+export declare const OVERLAY_SCROLLBAR_SIZE = 12;
+export interface OverlayScrollbarsProps {
+    /** 실제로 스크롤하는 요소. 이 컴포넌트는 그 요소의 형제로 선다 */
+    scrollRef: RefObject<HTMLElement | null>;
+    /**
+     * 세로 막대를 그릴지. **스크롤이 실제로 걸린 축만 켠다** — `overflow-y: hidden` 인데
+     * 켜 두면 넘친 콘텐츠 때문에 못 움직이는 막대가 뜬다.
+     */
+    vertical?: boolean;
+    /** 가로 막대를 그릴지. 위와 같다 */
+    horizontal?: boolean;
+    /**
+     * true면 **스크롤하는 동안에만** 막대를 보인다. 멎으면 페이드로 사라진다.
+     *
+     * 끄고 두면 막대가 늘 서서 "여기는 스크롤된다"를 알린다 — 그 신호를 포기하는 대신
+     * 화면이 조용해진다. 끌고 있는 동안에는 손에서 사라지면 안 되므로 시간을 재지 않는다.
+     */
+    autoHide?: boolean;
+}
+export declare function OverlayScrollbars({ scrollRef, vertical: showVertical, horizontal: showHorizontal, autoHide, }: OverlayScrollbarsProps): import("react").JSX.Element;

package/dist/lib/row-metrics.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 가변 행 높이 가상 스크롤의 계산부 — DOM 을 모르는 순수 자료구조다.
+ * `SSelect`(드롭다운 목록)와 `STable`(본문 행)이 함께 쓴다.
+ *
+ * 아직 그려지지 않은 행은 추정치로 두고, 화면에 나온 행은 실측으로 덮는다. 그래서
+ * "모든 행이 같은 높이"라는 가정 없이도 스크롤 위치 ↔ 행 인덱스를 오갈 수 있다 —
+ * depth 그룹 헤더처럼 리프와 높이가 다른 행이 섞여도 어긋나지 않는다.
+ * (Quasar QVirtualScroll 의 `virtual-scroll-item-size` 가 "추정치일 뿐"인 것과 같은 모델)
+ *
+ * 수천 행에서 렌더마다 새 배열을 만들면 그 자체가 비용이라, 제자리에서 고친다.
+ * 소유자는 ref 하나로 들고 있고, 화면에 반영할 필요가 있을 때만 리렌더를 건다.
+ */
+export interface RowMetrics {
+    /** 행별 높이. 실측 전에는 `estimate` 가 들어 있다 */
+    sizes: number[];
+    /** 실측을 마친 행인지 — 추정치를 평균에 섞지 않으려고 구분한다 */
+    measured: boolean[];
+    /** `offsets[i]` = 0..i-1 행 높이의 합. 길이는 `sizes.length + 1` 이라 마지막이 전체 높이다 */
+    offsets: number[];
+    /** 아직 안 그려진 행에 쓸 높이. 실측이 쌓일수록 그 평균으로 수렴한다 */
+    estimate: number;
+    /** 추정치 갱신용 누적 — 평균을 매번 다시 훑지 않으려고 합과 개수를 들고 있는다 */
+    measuredCount: number;
+    measuredTotal: number;
+    /** 이 인덱스부터 `offsets` 가 낡았다. `Infinity` 면 최신 */
+    dirtyFrom: number;
+}
+export declare function createRowMetrics(count: number, estimate: number): RowMetrics;
+/**
+ * 목록 길이가 바뀌었을 때 표를 맞춘다.
+ *
+ * 늘어난 만큼은 추정치로 채우고 **앞쪽 실측은 그대로 둔다** — 무한 로딩은 뒤에 이어붙이는
+ * 것이라, 여기서 표를 새로 만들면 이미 잰 높이를 버리고 스크롤이 튄다. 줄어들 때는 잘라낸다
+ * (검색으로 목록이 좁아지는 경우인데, 그때는 같은 인덱스가 다른 행이므로 실측도 함께 버린다).
+ */
+export declare function resizeRowMetrics(metrics: RowMetrics, count: number): void;
+/** 목록이 통째로 다른 것으로 갈렸을 때 — 실측을 전부 버리고 추정치만 남긴다 */
+export declare function resetRowMetrics(metrics: RowMetrics, count: number): void;
+/**
+ * 실측 높이를 반영한다. 값이 실제로 달라졌으면 `true`.
+ *
+ * 추정치도 실측 평균으로 함께 끌어당긴다 — 한 번도 안 그려진 뒤쪽 수천 행의 높이가
+ * 그만큼 사실에 가까워져, 스크롤바 길이와 "끝까지 내렸을 때"의 위치가 맞는다.
+ * 다만 1px 미만의 흔들림으로 표 전체를 다시 세우지는 않는다.
+ */
+export declare function setRowSize(metrics: RowMetrics, index: number, size: number): boolean;
+/**
+ * 낡은 구간의 누적 오프셋을 다시 센다. 이미 최신이면 아무 일도 하지 않는다.
+ * 바뀐 지점 앞은 그대로 두고 거기서부터만 이어 세므로, 아래쪽 행을 재도 전체를 훑지 않는다.
+ */
+export declare function rebuildOffsets(metrics: RowMetrics): void;
+/** 목록 전체 높이 */
+export declare function totalSize(metrics: RowMetrics): number;
+/** `index` 번 행의 위쪽 끝 y */
+export declare function offsetOf(metrics: RowMetrics, index: number): number;
+export declare function sizeOf(metrics: RowMetrics, index: number): number;
+/**
+ * y 좌표에 놓인 행의 인덱스 (이진 탐색). 목록 끝을 넘으면 마지막 행을 준다.
+ * 수천 행에서 스크롤마다 훑으면 그게 곧 렉이라 선형 탐색을 쓰지 않는다.
+ */
+export declare function indexAtOffset(metrics: RowMetrics, y: number): number;

package/dist/lib/row-motion.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 표 행 펼침·접힘 모션 — `STreeTable` 의 하위 행과 `STable` 의 상세 영역(`renderExpansion`)이 같은
+ * 서랍 움직임을 쓴다. 하나를 바꾸면 두 표가 함께 바뀐다.
+ *
+ * 표 행(`<tr>`)은 높이를 0 부터 늘리고 줄일 수 없어서, 높이 대신 **보이는 위치**를 움직인다(FLIP).
+ * 행은 처음부터 제자리에 넣어 두고, 아래 행은 늘어난 높이만큼 위에서 출발해 제자리로 내려오며,
+ * 펼쳐지는 덩어리는 바로 위 행 아랫변 밑으로 나온 부분만 보이게 잘라 낸다. 접힘은 그 반대다.
+ * 행 높이는 그대로라 가상 스크롤의 실측도 흔들리지 않는다.
+ */
+/** 행 식별 값 */
+export type RowMotionKey = string | number;
+/**
+ * 펼침·접힘 모션. 접힘이 더 짧고 ease-in 인 것은 닫는 쪽이 빨리 비켜 줘야 다음 조작이 기다리지 않기 때문이다.
+ * 해당하는 토큰이 아직 없어 여기에 둔다.
+ */
+export declare const EXPAND_MOTION: {
+    readonly duration: 220;
+    readonly easing: "ease-out";
+};
+export declare const COLLAPSE_MOTION: {
+    readonly duration: 140;
+    readonly easing: "ease-in";
+};
+export declare function sameKeys(a: ReadonlySet<RowMotionKey>, b: ReadonlySet<RowMotionKey>): boolean;
+/** 모션을 줄인 환경이거나 Web Animations 가 없는 환경(SSR·테스트용 DOM)에서는 움직이지 않고 바로 그린다 */
+export declare function motionAllowed(): boolean;
+/** 진행 중인 펼침·접힘 모션 하나 */
+export interface RowMotion {
+    /** 펼쳐지거나 접히는 하위 행 */
+    keys: ReadonlySet<RowMotionKey>;
+    /** 끝났을 때 열린 정도 — 펼침 1, 접힘 0 */
+    to: 0 | 1;
+    /** 접힘이 끝까지 가서 남겨 둔 행을 뺄 차례인가 */
+    done: boolean;
+    /** 끝까지 가면 true, 도중에 취소되면 false */
+    finished: Promise<boolean>;
+    /** 지금 열린 정도 (0 닫힘 ~ 1 열림) — 도중에 되돌릴 때 여기서 이어 간다 */
+    openness: () => number;
+    cancel: () => void;
+}
+/**
+ * 펼쳐지는 행 덩어리(하위 행·상세 영역)를 열린 정도 `from` 에서 `to` 로 움직인다.
+ *
+ * 열린 정도 s 에서 덩어리 아래 행은 `덩어리 높이 × (1 - s)` 만큼 위에 있고, 덩어리 안 행도 같이 올라가
+ * 바로 위 행 아랫변 밑으로 나온 부분만 보인다. 그래서 잘려 나가는 자리와 올라오는 행이 겹치지 않는다.
+ * 여러 부모가 한 번에 바뀌면 덩어리가 여럿이고, 아래 행은 지나온 덩어리 높이를 모두 더한 만큼 움직인다.
+ */
+export declare function startRowMotion({ scrollEl, isInBlock, blockKeys, from, to, }: {
+    scrollEl: HTMLElement;
+    /** 그려진 행(`<tr>`)이 펼쳐지는 덩어리에 드는가 */
+    isInBlock: (tr: HTMLElement) => boolean;
+    /** 펼쳐지는 덩어리의 키 — 도중에 되돌리는지 가릴 때 쓴다 */
+    blockKeys: ReadonlySet<RowMotionKey>;
+    from: number;
+    to: 0 | 1;
+}): RowMotion | null;

package/dist/lib/scrollbar.d.ts

@@ -1,6 +1,5 @@
 /**
  * 공용 커스텀 스크롤바 클래스.
- * Stencil의 styles/scrollbar.scss mixin과 짝을 이루는 단일 기준이며,
  * 스크롤 영역을 가진 컴포넌트는 DOM을 감싸지 않고 이 클래스를 직접 붙여 쓴다.
  *
  * SVG 스펙: 트랙 12px / 썸 8px(grey-45, 2px 인셋, radius 4).
@@ -20,7 +19,7 @@ export declare const SCROLLBAR_CLASS: string;
 export declare const SCROLLBAR_HIDDEN_CLASS = "[scrollbar-width:none] [&::-webkit-scrollbar]:hidden";
 /**
  * background: 트랙 배경을 채운다. 콘텐츠 영역 배경은 바뀌지 않는다.
- * Stencil 의 scrollbar-track-bg($color) mixin 과 짝이며, 이쪽은 기본값 grey-10 에 해당한다.
+ * 트랙 색은 grey-10 이다.
  * Tailwind 는 소스에 문자열로 박힌 클래스만 수집하므로 색을 인자로 받는 함수로 만들 수 없다.
  * 색이 필요하면 아래 WHITE 처럼 리터럴 상수를 하나 더 만든다.
  *