open-grid 1.2.0 → 1.2.1

package/dist/types/core/RangeSelectionManager.d.ts

@@ -6,6 +6,11 @@ import { FlatRowModel } from './FlatRowModel.js';
 import { GridOptions } from './types.js';
 import { RangeStats } from './range/RangeQuery.js';
 import { CellRange, Direction, FillMode, FillPreview } from './range/types.js';
+/**
+ * RangeSelectionManager 가 OpenGrid 서브시스템을 읽고 쓰기 위해 주입받는 클로저 묶음.
+ * / Closures injected into RangeSelectionManager so it can read and write OpenGrid subsystem
+ * state without owning it directly.
+ */
 export interface RangeSelectionDeps<T extends Record<string, any>> {
     getOptions: () => Required<GridOptions<T>>;
     getData: () => DataLayer<T>;
@@ -13,15 +18,21 @@ export interface RangeSelectionDeps<T extends Record<string, any>> {
     getFlatModel: () => FlatRowModel;
     getRenderer: () => GridRenderer | null;
     getEditMgr: () => CellEditManager<T>;
+    /** 포커스 셀을 이동. / Move the focused cell. */
     setFocusCell: (ri: number, ci: number) => void;
+    /** 배치 경유 셀 쓰기(재렌더 ≤1회, C2.1). / Batched cell write (at most one re-render, C2.1). */
     writeCells: (patches: Array<{
         rowIndex: number;
         field: string;
         value: any;
     }>) => number;
+    /** 셀의 화면 표시 텍스트(포맷 적용). / The cell's display text (formatted). */
     getDisplayValue: (ri: number, field: string) => string;
+    /** 그리드 이벤트 발행. / Emit a grid event. */
     emit: (event: string, ...args: any[]) => void;
+    /** 현재 가시 범위를 재렌더. / Re-render the currently visible range. */
     doRender: () => void;
+    /** aria-live 영역에 메시지를 공지. / Announce a message via the aria-live region. */
     announce: (msg: string) => void;
     /** i18n: 범위 선택/채우기 announce·aria 해석. / i18n: resolve range selection/fill announce & aria. */
     t: (key: string, params?: Record<string, string | number>) => string;
@@ -29,6 +40,17 @@ export interface RangeSelectionDeps<T extends Record<string, any>> {
     offsetFormula?: (rowId: string, field: string, dRow: number, dCol: number) => string;
     setCellFormulaByRowId?: (rowId: string, field: string, formula: string) => void;
 }
+/**
+ * F1 범위 선택 + 채우기 매니저. / F1 range selection + fill manager.
+ *
+ * 포인터 드래그·클릭·Shift+화살표로 셀 범위를 선택하고, 채우기 핸들 드래그/Ctrl+D·R 로 값·수식을
+ * 복제하며, 탭 구분 텍스트 복사/붙여넣기(TSV)까지 담당한다. 선택 모델 자체는 헤드리스
+ * `RangeModel`(core/range/*)이 소유하고, 이 클래스는 DOM 이벤트·오버레이 렌더·그리드 배선만
+ * 책임진다. / Handles cell-range selection via pointer drag, click, and Shift+Arrow; duplicates
+ * values/formulas via fill-handle drag or Ctrl+D/R; and drives tab-separated (TSV) copy/paste.
+ * The selection model itself is owned by the headless `RangeModel` (core/range/*); this class is
+ * responsible only for DOM events, overlay rendering, and grid wiring.
+ */
 export declare class RangeSelectionManager<T extends Record<string, any> = any> {
     private _d;
     private _model;
@@ -46,47 +68,139 @@ export declare class RangeSelectionManager<T extends Record<string, any> = any>
     private _handleEl;
     private _mountedWrap;
     constructor(deps: RangeSelectionDeps<T>);
+    /** 범위 선택 기능이 켜져 있는지. / Whether range selection is enabled.
+     * @returns 켜져 있으면 true / True if enabled */
     isEnabled(): boolean;
     private _rangeOpts;
     private _editorActive;
+    /** 현재 범위 선택이 있는지. / Whether there is an active range selection. */
     hasSelection(): boolean;
+    /** 현재 선택된 모든 범위(multiRange 지원 시 다건). / All currently selected ranges (multiple when multiRange is enabled). */
     getRangeSelection(): CellRange[];
+    /** 마지막(활성) 범위. 없으면 `null`. / The last (active) range, or `null` if none. */
     getActiveRange(): CellRange | null;
+    /** 채우기 핸들 드래그 중인 미리보기 범위. 없으면 `null`. / The fill preview range while dragging the fill handle, or `null`. */
     getFillPreview(): FillPreview | null;
+    /** 활성 범위의 셀 값들을 2차원 배열로 반환(범위 없으면 빈 배열).
+     * / Return the active range's cell values as a 2D array (empty array if no active range). */
     getRangeValues(): any[][];
+    /** 활성 범위의 합계/평균 등 통계(범위 없으면 `null`).
+     * / Statistics (sum/average/etc.) for the active range, or `null` if none. */
     getRangeStats(): RangeStats | null;
     private _queryCtx;
+    /**
+     * 셀 위 마우스 다운 — 드래그 선택을 시작한다(UC-1). / Mouse-down on a cell — begins drag selection (UC-1).
+     *
+     * @param ri - 시작 행 인덱스 / Starting row index
+     * @param ci - 시작 열 인덱스 / Starting column index
+     * @param e - 원본 마우스 이벤트(Ctrl/Meta=추가선택, Shift=확장) / Original mouse event (Ctrl/Meta = additive, Shift = extend)
+     */
     handleCellMouseDown(ri: number, ci: number, e: MouseEvent): void;
+    /**
+     * 드래그 중 셀 위 마우스 이동 — 범위를 갱신하고 가장자리 근처면 자동 스크롤한다.
+     * / Mouse move over a cell while dragging — updates the range and auto-scrolls near edges.
+     *
+     * @param ri - 현재 행 인덱스 / Current row index
+     * @param ci - 현재 열 인덱스 / Current column index
+     * @param e - 원본 마우스 이벤트(자동 스크롤 거리 계산용) / Original mouse event (used to compute auto-scroll distance)
+     */
     handleCellMouseMove(ri: number, ci: number, e: MouseEvent): void;
+    /** 드래그 종료 — 자동 스크롤 정지 + 선택 확정 + 이벤트 발행. 셀 밖 mouseup(document 폴백)도 이 경로를 탄다.
+     * / End the drag — stops auto-scroll, finalizes the selection, and emits events. A mouseup
+     * outside any cell (document-level fallback) also flows through this path. */
     handleCellMouseUp(_ri: number, _ci: number, _e: MouseEvent): void;
+    /**
+     * 셀 클릭 처리 — 일반 클릭은 단일 셀 선택, Shift+클릭은 활성 범위를 확장한다(UC-2).
+     * / Handle a cell click — a plain click selects a single cell; Shift+click extends the active range (UC-2).
+     *
+     * @param ri - 클릭된 행 인덱스 / Clicked row index
+     * @param ci - 클릭된 열 인덱스 / Clicked column index
+     * @param shiftKey - Shift 키가 눌려 있었는지 / Whether the Shift key was held
+     */
     handleClick(ri: number, ci: number, shiftKey: boolean): void;
+    /**
+     * Shift+화살표로 활성 범위를 방향으로 확장한다(UC-3). / Extend the active range in a direction via Shift+Arrow (UC-3).
+     *
+     * @param dir - 확장 방향 / Direction to extend
+     */
     extendFocus(dir: Direction): void;
+    /** 범위 선택을 해제한다(선택 없으면 no-op). / Clear the range selection (no-op if nothing is selected). */
     clear(): void;
+    /** `clear()` 별칭(공개 API 명명 일관성). / Alias for `clear()` (public API naming consistency). */
     clearRangeSelection(): void;
+    /**
+     * 범위 선택을 프로그램적으로 지정한다(§6.2 공개 API). / Programmatically set the range selection (§6.2 public API).
+     *
+     * @param range - 지정할 범위(배열이면 첫 요소만 사용) / Range to set (if an array, only the first element is used)
+     * @example
+     * grid.setRangeSelection({ startRow: 0, endRow: 2, startCol: 0, endCol: 1 });
+     */
     setRangeSelection(range: CellRange | CellRange[]): void;
-    /** applySort/applyFilter 직후 호출(C0.5, §2.5) — 선택은 rowId 집합 기준으로 재투영(해제 아님). */
+    /** applySort/applyFilter 직후 호출(C0.5, §2.5) — 선택은 rowId 집합 기준으로 재투영(해제 아님).
+     * / Called right after applySort/applyFilter (C0.5, §2.5) — re-projects the selection by its
+     * rowId set instead of clearing it. */
     reproject(): void;
     private _afterModelChange;
     private _announceSelection;
+    /**
+     * Ctrl+D(아래로 채우기)/Ctrl+R(오른쪽으로 채우기) 키보드 단축키(UR-5, §3.3).
+     * / Ctrl+D (fill down) / Ctrl+R (fill right) keyboard shortcuts (UR-5, §3.3).
+     *
+     * @param axis - 채우기 방향 / Fill direction
+     */
     ctrlFill(axis: 'down' | 'right'): void;
-    /** 공개 API(§6.2): source→target 채우기. axis 는 두 rect 의 상대 위치로 추론한다. */
+    /** 공개 API(§6.2): source→target 채우기. axis 는 두 rect 의 상대 위치로 추론한다.
+     * / Public API (§6.2): fill from source to target. The axis is inferred from the two rects'
+     * relative position.
+     *
+     * @param source - 채우기 원본 범위 / Source range to fill from
+     * @param target - 채우기 대상 범위 / Target range to fill into
+     * @param mode - 채우기 모드(기본 'copy') / Fill mode (default 'copy')
+     * @example
+     * grid.fillRange(
+     *   { startRow: 0, endRow: 0, startCol: 0, endCol: 0 },
+     *   { startRow: 1, endRow: 3, startCol: 0, endCol: 0 },
+     *   'series',
+     * );
+     */
     fillRange(source: CellRange, target: CellRange, mode?: FillMode): void;
     private _isEditable;
     private _commitFill;
-    /** KeyboardManager._copyToClipboard 가 소비. 범위 없으면 null(호출측이 기존 경로로 폴백). */
+    /** KeyboardManager._copyToClipboard 가 소비. 범위 없으면 null(호출측이 기존 경로로 폴백).
+     * / Consumed by KeyboardManager._copyToClipboard. Returns null when there is no active range
+     * (the caller falls back to its existing path).
+     *
+     * @returns 활성 범위의 TSV 텍스트, 없으면 `null` / TSV text for the active range, or `null`
+     */
     copyText(): string | null;
-    /** KeyboardManager._pasteFromClipboard 가 소비. true = 처리함(배치 경유), false = 범위 없음(폴백). */
+    /** KeyboardManager._pasteFromClipboard 가 소비. true = 처리함(배치 경유), false = 범위 없음(폴백).
+     * / Consumed by KeyboardManager._pasteFromClipboard.
+     *
+     * @param text - 붙여넣을 TSV 텍스트 / TSV text to paste
+     * @returns 처리했으면 true(배치 경유), 활성 범위가 없으면 false(호출측 폴백)
+     *  / True if handled (batched write); false if there is no active range (caller falls back)
+     */
     pasteText(text: string): boolean;
     private _maybeAutoscroll;
     private _scrollSpeed;
     private _runAutoscroll;
     private _stopAutoscroll;
-    /** bodyWrap 자식으로 오버레이 1회 생성(renderBody 파괴 회피, CON-3 해법). */
+    /** bodyWrap 자식으로 오버레이 1회 생성(renderBody 파괴 회피, CON-3 해법).
+     * / Creates the overlay once as a child of bodyWrap (avoids renderBody teardown; the CON-3 fix).
+     *
+     * @param bodyWrap - 그리드 바디 래퍼 엘리먼트 / The grid body wrapper element
+     */
     mount(bodyWrap: HTMLElement): void;
-    /** _doRender 매 호출 뒤 실행(M-6 통합점) — 코너 셀 실측 → 연속 테두리/핸들/프리뷰 갱신(QA-2, CON-4). */
+    /** _doRender 매 호출 뒤 실행(M-6 통합점) — 코너 셀 실측 → 연속 테두리/핸들/프리뷰 갱신(QA-2, CON-4).
+     * / Runs after every _doRender call (M-6 integration point) — measures the corner cells and
+     * updates the contiguous border/handle/preview overlay (QA-2, CON-4). */
     repaint(): void;
     private _hideOverlay;
-    /** OpenGrid._doRender 가 renderBody extraOpts 로 전달(M-6). */
+    /** OpenGrid._doRender 가 renderBody extraOpts 로 전달(M-6).
+     * / Passed by OpenGrid._doRender as renderBody's extraOpts (M-6).
+     *
+     * @returns 현재 선택 범위들을 담은 렌더 옵션 조각 / A render-options fragment carrying the current selected ranges
+     */
     getOverlayExtraOpts(): {
         _rangeRects: CellRange[];
     };

package/dist/types/core/RenderController.d.ts

@@ -22,6 +22,17 @@ import { GridOptions } from './types.js';
  * 값(컬럼폭·옵션 등)은 늦은-null / 재할당(worksheet 전환 시 colLayout 교체)을 견디도록
  * 전부 getter 클로저로 읽는다. `fallbackViewportHeight` 클램프 시맨틱과 RenderFrame 구성은
  * 원본과 1:1 동일하다(회귀 0).
+ * / Dependency contract for the sole entry point of the render loop (R5, §3.1 C4, §6-R5),
+ * moving `_onResize`/`_recalcWidths`/`_renderHeader`/`_syncHeaderLayout`/`_doRender`/`_visRange`
+ * (plus the private helpers `_visCount`/`_paginationHeight`) out of the `OpenGrid` God object
+ * with **behavior unchanged**.
+ *
+ * Strangler principle (A2): collaborators (GridRenderer/VirtualScroll/Pagination, etc.) are
+ * still created and owned by `OpenGrid._mount`; they are only **injected** here via the
+ * `*Deps` closure-inversion pattern. Values (column widths, options, etc.) are all read
+ * through getter closures so they tolerate late-null / reassignment (colLayout swap on
+ * worksheet switch). The `fallbackViewportHeight` clamp semantics and RenderFrame construction
+ * are 1:1 identical to the original (zero regression).
  */
 export interface RenderControllerDeps<T extends Record<string, any> = any> {
     getContainer: () => HTMLElement;
@@ -35,6 +46,7 @@ export interface RenderControllerDeps<T extends Record<string, any> = any> {
     getMergeEngine: () => MergeEngine;
     getColWidths: () => number[];
     setColWidths: (widths: number[]) => void;
+    /** 사용자가 직접 조절한 컬럼폭(리사이즈 시 보존 대상). / User-resized column widths (preserved across recalcWidths). */
     getUserWidths: () => Map<string, number>;
     getSfMgr: () => SortFilterManager<T>;
     getRowMgr: () => RowManager<T>;
@@ -42,24 +54,68 @@ export interface RenderControllerDeps<T extends Record<string, any> = any> {
     getGrpMgr: () => GroupTreeManager<T>;
     getDetailMgr: () => DetailManager<T>;
     getRangeMgr: () => RangeSelectionManager<T>;
+    /** F2: detail 렌더 컨텍스트 조립(비활성 시 undefined). / F2: build the detail render context (undefined when inactive). */
     buildDetailRenderContext: () => DetailRenderContext | undefined;
+    /** 푸터 합계 영역 재렌더. / Re-render the footer summary area. */
     renderFooterEl: () => void;
 }
+/**
+ * 렌더 루프의 유일 진입점. / Sole entry point of the render loop.
+ *
+ * 리사이즈·헤더/본문 렌더·뷰포트 높이 동기화·가시 범위 계산을 담당한다(R5).
+ * / Handles resize, header/body rendering, viewport-height sync, and visible-range
+ * computation (R5).
+ */
 export declare class RenderController<T extends Record<string, any> = any> {
     private _deps;
     private _autoHeightWarned;
     constructor(deps: RenderControllerDeps<T>);
+    /** @internal */
     private _paginationHeight;
+    /**
+     * 컨테이너 리사이즈에 반응해 폭 재계산 → 헤더 재렌더 → 본문 재렌더를 수행한다.
+     * / Responds to a container resize: recalculates widths, re-renders the header, then
+     * re-renders the body.
+     */
     onResize(): void;
+    /**
+     * 전체 폭에서 고정 UI 요소(state/드래그/행번호/체크 컬럼)를 뺀 뒤 컬럼폭을 재계산한다.
+     * 사용자가 직접 조절한 폭은 보존한다.
+     * / Recalculate column widths from the total width minus fixed UI elements (state/drag/
+     * row-number/check columns). User-resized widths are preserved.
+     *
+     * @param totalWidth - 컨테이너 전체 폭(px) / Total container width in px
+     */
     recalcWidths(totalWidth: number): void;
+    /**
+     * 헤더(컬럼 제목 행)를 다시 그린다. / Re-render the header (column title row).
+     */
     renderHeader(): void;
     /**
      * 렌더된 헤더의 실제 높이를 측정해 본문(bodyWrap) 높이와 뷰포트 높이에 반영한다.
      * 줄바꿈이 없는 헤더는 측정 높이가 headerHeight 이하라 기존 고정 동작과 동일하다.
      * (public: OpenGrid 가 `_syncHeaderLayout` 위임으로 노출 — 특성화 테스트가 직접 호출한다.)
+     * / Measures the rendered header's actual height and applies it to the body (bodyWrap)
+     * height and viewport height. Headers without wrapping measure at or below `headerHeight`,
+     * so existing fixed-height behavior is unchanged. (Public: `OpenGrid` exposes this via a
+     * `_syncHeaderLayout` delegate — characterization tests call it directly.)
      */
     syncHeaderLayout(): void;
+    /**
+     * 지정 범위의 본문 행을 렌더한다(autoHeight 활성 시 범위 인자를 무시하고 전체 행을 렌더).
+     * / Render body rows within the given range (when autoHeight is active, the range
+     * arguments are ignored and all rows are rendered).
+     *
+     * @param startIndex - 렌더 시작 flat index / Starting flat index to render
+     * @param endIndex - 렌더 끝 flat index / Ending flat index to render
+     */
     doRender(startIndex: number, endIndex: number): void;
+    /**
+     * 현재 화면에 보이는 행 범위를 반환한다. / Return the currently visible row range.
+     *
+     * @returns `[시작, 끝]` flat index 쌍 / `[start, end]` flat index pair
+     */
     visRange(): [number, number];
+    /** @internal */
     private _visCount;
 }

package/dist/types/core/RowManager.d.ts

@@ -1,29 +1,84 @@
 import { DataLayer } from './DataLayer.js';
+/**
+ * 행 선택(selection)과 체크(checkbox) 상태를 관리하는 매니저. / Manages row selection and checkbox state.
+ *
+ * 두 상태는 서로 독립적이다 — 선택은 활성/포커스 개념(단일 행만 유지 가능),
+ * 체크는 다중 표시(예: 체크박스 컬럼)를 위한 별도 집합이다.
+ * / The two states are independent — selection tracks an active/focus concept
+ * (can be limited to a single row), while checks are a separate set for
+ * multi-marking (e.g. a checkbox column).
+ */
 export declare class RowManager<T extends Record<string, any> = any> {
     private _selectedRows;
     private _checkedRows;
     private _data;
     constructor(data: DataLayer<T>);
+    /** 선택된 행 인덱스 집합(원본 참조). / Set of selected row indexes (live reference). */
     get selectedRows(): Set<number>;
+    /** 체크된 행 인덱스 집합(원본 참조). / Set of checked row indexes (live reference). */
     get checkedRows(): Set<number>;
+    /**
+     * 단일 행만 선택한다(기존 선택은 모두 해제). / Select exactly one row (clears any prior selection).
+     *
+     * @param ri - 선택할 행의 flat index / Flat index of the row to select
+     */
     selectSingle(ri: number): void;
+    /**
+     * 지정 행의 선택 상태를 토글한다(다중 선택 누적). / Toggle a row's selection state (accumulates for multi-select).
+     *
+     * @param ri - 토글할 행의 flat index / Flat index of the row to toggle
+     */
     selectToggle(ri: number): void;
+    /** 모든 행 선택을 해제한다. / Clear every row selection. */
     clearSelection(): void;
+    /**
+     * 지정 행의 체크 상태를 설정한다. / Set the checked state of a single row.
+     *
+     * @param ri - 대상 행의 flat index / Flat index of the target row
+     * @param checked - 체크 여부 / Whether the row should be checked
+     */
     check(ri: number, checked: boolean): void;
+    /**
+     * 전체 행을 체크하거나 전체 해제한다. / Check or uncheck every row.
+     *
+     * @param checked - `true` 면 전체 체크, `false` 면 전체 해제 / `true` to check all, `false` to clear all
+     * @param totalRows - 전체 행 수(체크 시 0..totalRows-1 을 채움) / Total row count (when checking, fills indexes 0..totalRows-1)
+     */
     checkAll(checked: boolean, totalRows: number): void;
+    /**
+     * 특정 컬럼 값이 주어진 목록에 포함된 행들을 체크한다. / Check every row whose column value is in the given list.
+     *
+     * @param field - 값을 비교할 컬럼 field 명 / Column field to compare values against
+     * @param values - 매칭 대상 값 목록 / Values to match against
+     */
     checkByValue(field: string, values: any[]): void;
+    /** 모든 체크를 해제한다. / Clear every checked row. */
     uncheckAll(): void;
+    /** @internal 미구현 스텁(rowId 기반 체크 API 예약). / @internal Unimplemented stub (reserved for a rowId-based check API). */
     checkById(_ids: string[]): void;
+    /** @internal 미구현 스텁(rowId 기반 체크 추가 API 예약). / @internal Unimplemented stub (reserved for a rowId-based add-check API). */
     addCheckById(_ids: string[]): void;
+    /** @internal 미구현 스텁(rowId 기반 체크 해제 API 예약). / @internal Unimplemented stub (reserved for a rowId-based uncheck API). */
     uncheckById(_ids: string[]): void;
+    /** 현재 선택된 행 데이터 배열을 반환한다(존재하지 않는 인덱스는 제외). / Return the currently selected row data (indexes with no backing row are skipped). */
     getSelections(): T[];
+    /** 체크된 행을 `{ row, rowIndex }` 쌍의 배열로 반환한다. / Return checked rows as an array of `{ row, rowIndex }` pairs. */
     getChecked(): Array<{
         row: T;
         rowIndex: number;
     }>;
+    /** 체크된 행의 데이터만 배열로 반환한다. / Return only the row data of checked rows. */
     getAllChecked(): T[];
+    /** 활성(선택) 행의 인덱스를 반환한다(없으면 -1). / Return the active (selected) row's index, or -1 if none. */
     getActiveRow(): number;
+    /**
+     * 지정 행을 활성 상태로 만든다(단일 선택과 동일 동작). / Make the given row active (same effect as single-select).
+     *
+     * @param index - 활성화할 행의 flat index / Flat index of the row to activate
+     */
     activate(index: number): void;
+    /** 선택을 해제한다(활성 행 없음). / Deselect (no active row). */
     deselect(): void;
+    /** 선택·체크 상태를 모두 초기화한다(주로 `setData`/`clearData` 시 호출). / Reset both selection and check state (typically called on `setData`/`clearData`). */
     reset(): void;
 }

package/dist/types/core/SkinRegistry.d.ts

@@ -1,53 +1,89 @@
 import { SkinTokenDelta } from './types.js';
+/** 스킨 정의 결과. / Result of a skin definition. */
 export interface SkinDefineResult {
-    /** 실제 등록된(가드레일 클램프가 반영된) 델타. */
+    /** 실제 등록된(가드레일 클램프가 반영된) 델타. / The actually registered delta (with guardrail clamps applied). */
     readonly delta: SkinTokenDelta;
-    /** 접근성 가드레일이 조정한 토큰 경고(있으면 콘솔에도 출력). */
+    /** 접근성 가드레일이 조정한 토큰 경고(있으면 콘솔에도 출력). / Warnings for tokens adjusted by accessibility guardrails (also logged to console when present). */
     readonly warnings: string[];
 }
-/** 스킨 델타가 색 리터럴을 담고 있는지 검사하고, 위반 시 던진다(FORM-only, Rule 2). */
+/**
+ * 스킨 델타가 색 리터럴을 담고 있는지 검사하고, 위반 시 던진다(FORM-only, Rule 2).
+ * / Assert a skin delta carries no color literal; throws on violation (FORM-only, Rule 2).
+ *
+ * @param id - 스킨 id / Skin id
+ * @param delta - 검사할 토큰 델타 / Token delta to validate
+ * @throws FORM 토큰이 아니거나 색 리터럴이 있으면 Error / Throws if a non-FORM token or a color literal is present
+ */
 export declare function assertFormOnly(id: string, delta: SkinTokenDelta): void;
 /**
- * HANMS 접근성 가드레일(불변식) 적용 — 정의 시점 클램프(§6.4, HANMS P0-4).
- *  - focus-width < 2px → 2px 로 클램프(가시 포커스 비협상).
+ * 접근성 가드레일(불변식) 적용 — 정의 시점 클램프(§6.4).
+ * / Apply accessibility guardrails (invariants) — clamp at definition time (§6.4).
+ *
+ *  - focus-width < 2px → 2px 로 클램프(가시 포커스 비협상). / clamp to 2px (visible focus is non-negotiable).
  *  - focus-style: none → solid.
+ *
  * 반환은 조정된 델타 + 경고 목록(silent override 아님 — 무엇을 클램프했는지 알린다).
+ * / Returns the adjusted delta plus a warning list (not a silent override — it reports what was clamped).
+ *
+ * @param id - 스킨 id / Skin id
+ * @param delta - 조정할 토큰 델타 / Token delta to adjust
+ * @returns 조정된 델타 + 경고 목록 / Adjusted delta plus warnings
  */
 export declare function applyGuardrails(id: string, delta: SkinTokenDelta): SkinDefineResult;
 /**
  * 프로세스 전역 스킨 등록소. defineSkin(사용자) 는 검증+가드레일+`<style>` 주입,
  * registerBuiltin(내장) 은 검증+가드레일만(CSS 는 skins.css 정적 번들 소유).
+ * / Process-global skin registry. `define` (user) does validation + guardrails + `<style>` injection;
+ * `registerBuiltin` (built-in) does validation + guardrails only (CSS is owned by the skins.css static bundle).
+ *
+ * @example
+ * skinRegistry.define('my-skin', { '--og-radius-md': '10px', '--og-border-style': 'solid' });
  */
 export declare class SkinRegistry {
     private _skins;
     private _styleEl;
-    /** 내장 스킨 등록(주입 없음 — CSS 는 skins.css 가 전달). 검증/가드레일은 동일 적용. */
+    /**
+     * 내장 스킨 등록(주입 없음 — CSS 는 skins.css 가 전달). 검증/가드레일은 동일 적용.
+     * / Register a built-in skin (no injection — CSS is delivered by skins.css). Validation/guardrails still apply.
+     *
+     * @param id - 스킨 id / Skin id
+     * @param delta - FORM 토큰 델타 / FORM token delta
+     */
     registerBuiltin(id: string, delta: SkinTokenDelta): void;
     /**
      * 사용자 스킨 등록. FORM-only 검증 + 가드레일 클램프 후 런타임 `<style>` 로
      * `.og-container[data-og-skin="id"]` 블록을 주입(브라우저 환경). 반환은 조정 결과.
+     * / Register a user skin. After FORM-only validation and guardrail clamps, injects a
+     * `.og-container[data-og-skin="id"]` block via a runtime `<style>` (browser env). Returns the adjusted result.
+     *
+     * @param id - 스킨 id / Skin id
+     * @param delta - FORM 토큰 델타 / FORM token delta
+     * @returns 조정된 델타 + 경고 목록 / Adjusted delta plus warnings
      */
     define(id: string, delta: SkinTokenDelta): SkinDefineResult;
+    /** 스킨 id 등록 여부. / Whether a skin id is registered. */
     has(id: string): boolean;
+    /** 등록된 스킨 델타 조회(없으면 undefined). / Get a registered skin delta (undefined if absent). */
     get(id: string): SkinTokenDelta | undefined;
-    /** 등록된 모든 스킨 id(내장 + 사용자). */
+    /** 등록된 모든 스킨 id(내장 + 사용자). / All registered skin ids (built-in + user). */
     list(): string[];
     /** 런타임 `<style>` 주입(테스트/SSR 등 document 없으면 no-op). 같은 태그를 누적 사용. */
     private _inject;
 }
-/** Sharp/Gothic — 엔터프라이즈 고밀도·각짐(§3.1). HANMS: APPROVE-WITH-GUARDRAIL(G-S1). */
+/** Sharp/Gothic — 엔터프라이즈 고밀도·각짐(§3.1). / Sharp/Gothic — enterprise high-density, squared corners (§3.1). */
 export declare const SKIN_SHARP: SkinTokenDelta;
-/** Rounded — 소비자 SaaS 소프트(§3.2). HANMS: APPROVE. */
+/** Rounded — 소비자 SaaS 소프트(§3.2). / Rounded — consumer-SaaS soft look (§3.2). */
 export declare const SKIN_ROUNDED: SkinTokenDelta;
-/** Stitch — 핸드크래프트(§3.3). HANMS: APPROVE-WITH-GUARDRAIL(G-ST1~3). 색(리넨/자수)은 theme 축. */
+/** Stitch — 핸드크래프트(§3.3). 색(리넨/자수)은 theme 축. / Stitch — handcrafted look (§3.3); color (linen/embroidery) lives on the theme axis. */
 export declare const SKIN_STITCH: SkinTokenDelta;
-/** Flat/Minimal — 플랫 2.0(§3.5). HANMS: APPROVE-WITH-GUARDRAIL(G-F1: 플로팅 표면 1px 보더). */
+/** Flat/Minimal — 플랫 2.0(§3.5). / Flat/Minimal — flat 2.0 (§3.5). */
 export declare const SKIN_FLAT: SkinTokenDelta;
-/** High-Contrast — 접근성 우선·레퍼런스(§3.6). HANMS: APPROVE(안전 폴백). */
+/** High-Contrast — 접근성 우선·레퍼런스(§3.6). / High-Contrast — accessibility-first reference skin (§3.6). */
 export declare const SKIN_HIGH_CONTRAST: SkinTokenDelta;
-/** Material/Elevated — Neumorph 대체(HANMS §3): 중간 반경 + 정직한 그림자 엘리베이션. APPROVE. */
+/** Material/Elevated — 중간 반경 + 정직한 그림자 엘리베이션. / Material/Elevated — medium radius plus honest shadow elevation. */
 export declare const SKIN_MATERIAL: SkinTokenDelta;
-/** 내장 스킨 카탈로그(HANMS 확정 6종, Neumorph 제외). id → 델타. */
+/** 내장 스킨 카탈로그(확정 6종). id → 델타. / Built-in skin catalog (6 finalized skins). id → delta. */
 export declare const BUILTIN_SKINS: ReadonlyArray<readonly [string, SkinTokenDelta]>;
-/** 프로세스 전역 기본 레지스트리 — 내장 스킨을 부트스트랩 등록(주입 없음, CSS=skins.css). */
+/** 프로세스 전역 기본 레지스트리 — 내장 스킨을 부트스트랩 등록(주입 없음, CSS=skins.css).
+ *  / Process-global default registry — bootstraps the built-in skins (no injection; CSS=skins.css). */
 export declare const skinRegistry: SkinRegistry;

package/dist/types/core/SortFilterManager.d.ts

@@ -3,37 +3,116 @@ import { ColumnLayout } from './ColumnLayout.js';
 import { VirtualScroll } from './VirtualScroll.js';
 import { Pagination } from './Pagination.js';
 import { SortItem, FilterItem } from './types.js';
+/**
+ * {@link SortFilterManager} 의존성 주입 계약. / Dependency-injection contract for {@link SortFilterManager}.
+ *
+ * 호스트 그리드가 데이터/렌더/i18n 접근을 함수로 넘겨 매니저를 데이터 소스와 분리한다.
+ * / The host grid passes data/render/i18n access as functions, decoupling the manager
+ * from its data source.
+ */
 export interface SortFilterDeps<T extends Record<string, any>> {
+    /** 현재 데이터 레이어 조회. / Look up the current data layer. */
     getData: () => DataLayer<T>;
+    /** 현재 컬럼 레이아웃 조회. / Look up the current column layout. */
     getColLayout: () => ColumnLayout<T>;
+    /** 통합검색(find) 필터 문자열 조회. / Look up the current find-filter string. */
     getFindFilter: () => string;
+    /** 가상 스크롤 인스턴스 조회(없으면 `null`). / Look up the virtual-scroll instance (or `null`). */
     getVs: () => VirtualScroll | null;
+    /** 페이지네이션 인스턴스 조회(없으면 `null`). / Look up the pagination instance (or `null`). */
     getPagination: () => Pagination | null;
+    /** 현재 그리드 옵션 조회. / Look up the current grid options. */
     getOptions: () => any;
+    /** 헤더(정렬/필터 표시)를 다시 그린다. / Re-render the header (sort/filter indicators). */
     renderHeader: () => void;
+    /** 바디를 다시 그린다. / Re-render the body. */
     doRender: () => void;
+    /** 스크린리더용 상태 안내. / Announce a status message for screen readers. */
     announce: (msg: string) => void;
     /** i18n: 정렬 상태어 + announce 해석. / i18n: resolve sort state words + announce. */
     t: (key: string, params?: Record<string, string | number>) => string;
+    /** 그리드 이벤트를 발행한다. / Emit a grid event. */
     emit: (event: string, ...args: any[]) => void;
-    /** C0.5/§2.5: 정렬/필터 후 F1 범위 선택을 rowId 집합 기준으로 재투영(해제 아님). */
+    /** C0.5/§2.5: 정렬/필터 후 F1 범위 선택을 rowId 집합 기준으로 재투영(해제 아님).
+     * / C0.5/§2.5: after sort/filter, re-project the F1 range selection by its rowId
+     * set instead of clearing it. */
     onReproject?: () => void;
 }
+/**
+ * 정렬·필터 상태와 적용을 담당하는 매니저. / Manages sort/filter state and their application.
+ *
+ * 정렬 목록(`SortItem[]`)과 컬럼별 필터(`FilterItem[]`)를 소유하고, 데이터 레이어에
+ * 적용한 뒤 헤더/바디 재렌더와 관련 이벤트 발행까지 처리한다.
+ * / Owns the sort list (`SortItem[]`) and per-column filters (`FilterItem[]`), applies
+ * them to the data layer, and drives header/body re-render plus related event emission.
+ */
 export declare class SortFilterManager<T extends Record<string, any> = any> {
     private _sortList;
     private _filters;
     private _d;
     constructor(deps: SortFilterDeps<T>);
+    /** 현재 정렬 목록(원본 참조). / Current sort list (live reference). */
     get sortList(): SortItem[];
+    /** 컬럼 field 별 필터 목록(원본 참조). / Filter items keyed by column field (live reference). */
     get filters(): Record<string, FilterItem[]>;
+    /**
+     * 헤더 정렬 클릭을 처리한다(단일/다중 정렬 토글). / Handle a header sort click (toggles single/multi sort).
+     *
+     * 같은 필드를 다시 클릭하면 asc→desc→해제 순으로 순환한다. `shiftKey` 와
+     * `multiSort` 옵션이 모두 켜져야 다중 정렬 목록에 누적된다.
+     * / Re-clicking the same field cycles asc → desc → removed. Multi-sort only
+     * accumulates when both `shiftKey` and the `multiSort` option are on.
+     *
+     * @param field - 정렬 대상 컬럼 field 명 / Column field to sort by
+     * @param shiftKey - 다중 정렬 결합 키(Shift) 눌림 여부 / Whether the multi-sort modifier (Shift) was held
+     */
     handleSortClick(field: string, shiftKey: boolean): void;
+    /**
+     * 프로그램적으로 정렬을 설정한다(단일 필드+방향, 또는 전체 정렬 목록). / Set sort programmatically (single field+direction, or a full sort list).
+     *
+     * @param fieldOrList - 정렬할 필드명, 또는 대체할 전체 `SortItem[]` / Field to sort by, or a full `SortItem[]` to replace the current list
+     * @param dir - `fieldOrList` 가 문자열일 때의 정렬 방향(기본 `'asc'`) / Sort direction when `fieldOrList` is a string (default `'asc'`)
+     * @example
+     * mgr.sort('name', 'desc');
+     * mgr.sort([{ field: 'age', dir: 'asc' }]);
+     */
     sort(fieldOrList: string | SortItem[], dir?: 'asc' | 'desc'): void;
+    /** 모든 정렬을 해제한다. / Clear all sorting. */
     resetSort(): void;
+    /**
+     * 초기 정렬 목록을 조용히 적용한다(렌더/이벤트 없이 데이터만). / Silently seed the initial sort list (data only, no render/events).
+     *
+     * @param sortList - 초기화 시 적용할 정렬 목록 / Sort list to apply at initialization
+     */
     initSort(sortList: SortItem[]): void;
+    /** 현재 정렬 목록의 복사본을 반환한다. / Return a copy of the current sort list. */
     getSortState(): SortItem[];
+    /**
+     * 특정 컬럼의 필터를 설정하고 적용한다. / Set and apply the filter for one column.
+     *
+     * @param field - 필터를 적용할 컬럼 field 명 / Column field to filter
+     * @param filterItems - 적용할 필터 조건 목록 / Filter conditions to apply
+     */
     setFilter(field: string, filterItems: FilterItem[]): void;
+    /**
+     * 필터를 해제한다(필드 지정 시 해당 필드만, 생략 시 전체). / Clear filters (one field if given, otherwise all).
+     *
+     * @param field - 해제할 컬럼 field 명. 생략하면 전체 필터 해제 / Column field to clear; omit to clear every filter
+     */
     resetFilter(field?: string): void;
+    /** 현재 컬럼별 필터 상태의 복사본을 반환한다. / Return a copy of the current per-column filter state. */
     getFilterState(): Record<string, FilterItem[]>;
+    /**
+     * 저장된 필터 상태를 복원하고 재적용한다(헤더/바디 재렌더는 호출측 책임). / Restore a saved filter state and reapply it (caller is responsible for header/body re-render).
+     *
+     * @param state - 복원할 컬럼별 필터 상태 / Per-column filter state to restore
+     */
     restoreFilter(state: Record<string, FilterItem[]>): void;
+    /**
+     * 통합검색 + 컬럼 필터를 데이터 레이어에 적용하고 행수를 재투영한다. / Apply find-filter and column filters to the data layer, then re-project row counts.
+     *
+     * 정렬과 달리 이 메서드는 헤더/바디를 직접 재렌더하지 않는다(호출측이 필요 시 처리).
+     * / Unlike sorting, this does not re-render header/body itself (callers handle that as needed).
+     */
     applyFilters(): void;
 }