open-grid 1.1.1 → 1.2.1

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

@@ -1,20 +1,54 @@
+/**
+ * 조직도 노드 카드의 컬럼(필드) 정의. / Column (field) definition for an org-chart node card.
+ */
 export interface OrgChartColumnDef {
+    /** 표시할 데이터 필드명. / Data field name to display. */
     field: string;
+    /** 셀 래퍼에 추가할 CSS 클래스명. / Extra CSS class name for the cell wrapper. */
     className?: string;
+    /** 인라인 스타일 문자열 또는 (값, 행)→스타일 함수. / Inline style string or (value, row)→style function. */
     style?: string | ((value: any, row: Record<string, any>) => string);
+    /** 커스텀 렌더러. 문자열 반환 시 innerHTML, 엘리먼트 반환 시 append. / Custom renderer; a string is set as innerHTML, an element is appended. */
     renderer?: (value: any, row: Record<string, any>) => HTMLElement | string;
 }
+/**
+ * 조직도 생성 옵션. / Org-chart construction options.
+ */
 export interface OrgChartOptions {
+    /** 각 행의 고유 id 필드명. / Field name holding each row's unique id. */
     idField: string;
+    /** 부모 id 를 담은 필드명(트리 구성 기준). / Field name holding the parent id (tree structure key). */
     parentIdField: string;
+    /** 노드 카드에 렌더할 컬럼 정의 배열. / Column definitions rendered inside each node card. */
     columns: OrgChartColumnDef[];
+    /** 노드 카드 너비(px). 기본 160. / Node card width in px. Default 160. @defaultValue 160 */
     nodeWidth?: number;
+    /** 노드 카드 높이(px). 기본 72. / Node card height in px. Default 72. @defaultValue 72 */
     nodeHeight?: number;
+    /** 레벨(세대) 간 세로 간격(px). 기본 52. / Vertical gap between levels in px. Default 52. @defaultValue 52 */
     levelGap?: number;
+    /** 형제 노드 간 가로 간격(px). 기본 20. / Horizontal gap between siblings in px. Default 20. @defaultValue 20 */
     siblingGap?: number;
+    /** 최초 로드 시 전체 펼침 여부. 기본 true. / Whether to expand all on first load. Default true. @defaultValue true */
     expandOnLoad?: boolean;
+    /** 노드 클릭 콜백 (id, 행데이터). / Node click callback (id, row data). */
     onNodeClick?: (id: any, data: Record<string, any>) => void;
 }
+/**
+ * 조직도 컴포넌트. / Org-chart component.
+ *
+ * 부모/자식 관계(idField/parentIdField)를 가진 평면 데이터를 트리로 구성해
+ * SVG 연결선 + 노드 카드로 렌더한다. 그리드와 독립된 standalone 컴포넌트다.
+ * / Builds a tree from flat parent/child data (idField/parentIdField) and renders it as
+ * SVG connectors plus node cards. A standalone component independent of the grid.
+ *
+ * @example
+ * const chart = new OrgChart('#org', {
+ *   idField: 'id', parentIdField: 'managerId',
+ *   columns: [{ field: 'name' }, { field: 'title' }],
+ * });
+ * chart.setData([{ id: 1, managerId: null, name: 'CEO', title: '대표' }]);
+ */
 export declare class OrgChart {
     private _container;
     private _opts;
@@ -22,12 +56,33 @@ export declare class OrgChart {
     private _roots;
     private _expandedKeys;
     private _selectedId;
+    /**
+     * @param selector - 마운트할 컨테이너 셀렉터 문자열 또는 엘리먼트 / Container selector string or element to mount into
+     * @param opts - 조직도 옵션 / Org-chart options
+     */
     constructor(selector: string | HTMLElement, opts: OrgChartOptions);
+    /**
+     * 조직도 데이터를 설정하고 렌더한다. / Set org-chart data and render.
+     *
+     * @param data - 부모/자식 관계를 가진 평면 행 배열 / Flat array of rows with parent/child relations
+     */
     setData(data: Record<string, any>[]): void;
+    /**
+     * COLOR 축 테마를 컨테이너에 설정한다. / Set the COLOR-axis theme on the container.
+     *
+     * @param theme - data-og-theme 값 / data-og-theme value
+     */
     setTheme(theme: string): void;
-    /** R12b: FORM(스킨) 축 — data-og-skin 을 자기 컨테이너에 설정(setTheme 과 동형, 색과 직교). */
+    /**
+     * R12b: FORM(스킨) 축 — data-og-skin 을 자기 컨테이너에 설정(setTheme 과 동형, 색과 직교).
+     * / R12b: FORM (skin) axis — set data-og-skin on the container (symmetric to setTheme, orthogonal to color).
+     *
+     * @param skin - data-og-skin 값 / data-og-skin value
+     */
     setSkin(skin: string): void;
+    /** 모든 노드를 펼친다. / Expand all nodes. */
     expandAll(): void;
+    /** 모든 노드를 접는다(루트만 표시). / Collapse all nodes (roots only). */
     collapseAll(): void;
     private _toggle;
     private _rebuild;

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

@@ -12,17 +12,34 @@
  * 본 커널은 단독 클래스로, OpenGrid 인스턴스를 host 로 받아 프로토타입 메서드를
  * 인스턴스 프로퍼티로 shadowing(순수 런타임 래핑, C1-clean) 한다. 소스 본문 0줄 수정.
  */
+/** override 커널의 호스트(임의 메서드를 가진 객체, 보통 OpenGrid 인스턴스). / Host of the override kernel (an object with arbitrary methods, usually an OpenGrid instance). */
 export interface OverrideKernelHost {
     [name: string]: any;
 }
-/** override() 호출 시 레이어가 받는 함수 시그니처: 첫 인자는 안쪽(원본 근접) 함수. */
+/**
+ * override() 호출 시 레이어가 받는 함수 시그니처: 첫 인자는 안쪽(원본 근접) 함수.
+ * / Layer function signature received by override(): the first argument is the inner (closest-to-original) function.
+ */
 export type OverrideLayer = (orig: (...args: any[]) => any, ...args: any[]) => any;
+/** override 옵션. / Override options. */
 export interface OverrideOptions {
-    /** 동일 name 재진입을 허용(정당한 재귀). 기본 false. */
+    /** 동일 name 재진입을 허용(정당한 재귀). 기본 false. / Allow re-entry for the same name (legitimate recursion). Default false. @defaultValue false */
     reentrant?: boolean;
-    /** 'fallback' → 레이어 예외 시 경고 후 orig 실행(멱등 가정). 미지정 시 strict(전파). */
+    /** 'fallback' → 레이어 예외 시 경고 후 orig 실행(멱등 가정). 미지정 시 strict(전파). / 'fallback' → on layer exception, warn then run orig (idempotent assumption); otherwise strict (propagate). */
     onError?: 'fallback';
 }
+/**
+ * `grid.override()` 확장 커널. / The `grid.override()` extension kernel.
+ *
+ * OpenGrid 인스턴스를 host 로 받아 프로토타입 메서드를 인스턴스 프로퍼티로 shadowing 한다
+ * (순수 런타임 래핑, 소스 본문 0줄 수정). FIFO 합성 + 재진입 가드 + 에러 격리를 제공한다.
+ * / Takes an OpenGrid instance as host and shadows prototype methods with instance properties
+ * (pure runtime wrapping, zero source edits). Provides FIFO composition, re-entry guarding, and error isolation.
+ *
+ * @example
+ * const k = new OverrideKernel(grid);
+ * k.override('setData', (orig, rows) => orig(rows.filter(r => r.active)));
+ */
 export declare class OverrideKernel {
     private _host;
     /** name → this-bound 원본 함수 (최초 1회 보존) */
@@ -39,32 +56,59 @@ export declare class OverrideKernel {
     private _strict;
     /** F3: 재귀 깊이 제한 */
     private _maxDepth;
+    /**
+     * @param host - override 대상 호스트 객체 / Host object to override
+     * @param opts - strict(기본 true, 예외 전파) / maxDepth(기본 32, 재귀 깊이 제한) / strict (default true, propagate) / maxDepth (default 32, recursion depth limit)
+     */
     constructor(host: OverrideKernelHost, opts?: {
         strict?: boolean;
         maxDepth?: number;
     });
     /**
-     * 메서드 override 등록.
-     * 1. 최초 1회 원본을 this-bound 로 보존.
-     * 2. 레이어 push (FIFO 등록순).
-     * 3. reduce 좌측폴드로 합성(나중 등록 = 최외곽).
-     * 4. 재진입 가드 + 에러 격리로 감싼 dispatcher 를 host[name] 인스턴스 프로퍼티에 할당.
+     * 메서드 override 등록. / Register a method override.
+     *
+     * 1. 최초 1회 원본을 this-bound 로 보존. / Preserve the original once, this-bound.
+     * 2. 레이어 push (FIFO 등록순). / Push the layer (FIFO registration order).
+     * 3. reduce 좌측폴드로 합성(나중 등록 = 최외곽). / Compose via reduce left-fold (later registration = outermost).
+     * 4. 재진입 가드 + 에러 격리로 감싼 dispatcher 를 host[name] 인스턴스 프로퍼티에 할당. / Assign a re-entry-guarded, error-isolated dispatcher to the host[name] instance property.
+     *
+     * @param name - override 대상 메서드명 / Method name to override
+     * @param fn - override 레이어(첫 인자는 안쪽 orig) / Override layer (first arg is the inner orig)
+     * @param opts - override 옵션 / Override options
+     * @returns 체이닝용 host / The host for chaining
      */
     override(name: string, fn: OverrideLayer, opts?: OverrideOptions): OverrideKernelHost;
     /** 합성된 dispatcher 생성. override/restore 시점마다 재구성. */
     private _buildDispatcher;
-    /** strategy 슬롯 등록 (Phase 2 매니저 배선용 API). */
+    /**
+     * strategy 슬롯 등록(매니저 배선용 API). / Register a strategy slot (manager-wiring API).
+     *
+     * @param slot - 전략 슬롯 이름 / Strategy slot name
+     * @param fn - 전략 함수 / Strategy function
+     * @returns 체이닝용 host / The host for chaining
+     */
     strategy(slot: string, fn: Function): OverrideKernelHost;
-    /** strategy 슬롯 조회 — 미등록 시 fallback 반환 (매니저 read API). */
+    /**
+     * strategy 슬롯 조회 — 미등록 시 fallback 반환(매니저 read API). / Read a strategy slot — returns fallback when unregistered (manager read API).
+     *
+     * @param slot - 전략 슬롯 이름 / Strategy slot name
+     * @param fallback - 미등록 시 반환할 기본 함수 / Default function returned when unregistered
+     * @returns 등록된 전략 또는 fallback / The registered strategy or fallback
+     */
     getStrategy<F extends Function>(slot: string, fallback: F): F;
-    /** 슬롯 등록 여부. */
+    /** 전략 슬롯 등록 여부. / Whether a strategy slot is registered. */
     hasStrategy(slot: string): boolean;
-    /** 단일 메서드 원본 복구. 없으면 no-op. */
+    /**
+     * 단일 메서드 원본 복구. 없으면 no-op. / Restore a single method's original; no-op if absent.
+     *
+     * @param name - 복구할 메서드명 / Method name to restore
+     * @returns 체이닝용 host / The host for chaining
+     */
     restore(name: string): OverrideKernelHost;
-    /** 전체 복구 + strategy clear. destroy 시 호출. */
+    /** 전체 복구 + strategy clear. destroy 시 호출. / Restore everything + clear strategies; called on destroy. */
     restoreAll(): OverrideKernelHost;
-    /** override 등록 여부. */
+    /** 해당 메서드가 override 등록돼 있는가. / Whether the given method is overridden. */
     hasOverride(name: string): boolean;
-    /** override 등록된 메서드 이름 목록. */
+    /** override 등록된 메서드 이름 목록. / List of overridden method names. */
     getOverrideNames(): string[];
 }

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

@@ -1,13 +1,25 @@
+/**
+ * 페이지 변경 시 전달되는 이벤트 페이로드. / Event payload delivered on a page change.
+ */
 export interface PageChangeEvent {
+    /** 현재(변경 후) 페이지 번호(1-base). / Current (post-change) page number (1-based). */
     page: number;
+    /** 페이지당 행 수. / Rows per page. */
     pageSize: number;
+    /** 전체 행 수. / Total row count. */
     totalRows: number;
+    /** 전체 페이지 수. / Total page count. */
     totalPages: number;
 }
+/** 페이지 변경 콜백. / Callback invoked on a page change. */
 export type PageChangeFn = (e: PageChangeEvent) => void;
+/** i18n: 페이지네이션 라벨 해석기(행/페이지·범위 배지·빈 상태). / i18n: pagination label resolver (rows-per-page, range badge, empty). */
+export type PaginationT = (key: string, params?: Record<string, string | number>) => string;
 /**
- * 그리드 하단 페이지네이션 UI + 상태 관리.
- * DataLayer의 _displayIndexes 슬라이싱을 담당.
+ * 그리드 하단 페이지네이션 UI + 상태 관리. / Grid bottom pagination UI plus state management.
+ *
+ * DataLayer의 `_displayIndexes` 슬라이싱 범위(`getRange`)를 계산해 넘겨준다.
+ * / Computes the slice range (`getRange`) used against DataLayer's `_displayIndexes`.
  */
 export declare class Pagination {
     private _el;
@@ -15,20 +27,47 @@ export declare class Pagination {
     private _pageSize;
     private _totalRows;
     private _onChange;
-    constructor(container: HTMLElement, pageSize: number, onChange: PageChangeFn);
+    private _t;
+    constructor(container: HTMLElement, pageSize: number, onChange: PageChangeFn, t?: PaginationT);
+    /** 현재 페이지 번호(1-base). / Current page number (1-based). */
     get page(): number;
+    /** 페이지당 행 수. / Rows per page. */
     get pageSize(): number;
+    /** 전체 페이지 수(최소 1). / Total page count (minimum 1). */
     get totalPages(): number;
-    /** 전체 행 수 갱신 → 현재 페이지 유효성 검사 후 재렌더 */
+    /**
+     * 전체 행 수 갱신 → 현재 페이지 유효성 검사 후 재렌더. / Update the total row count, clamp the current page if needed, and re-render.
+     *
+     * @param n - 새 전체 행 수 / New total row count
+     */
     setTotalRows(n: number): void;
+    /**
+     * 페이지당 행 수를 변경하고 1페이지로 리셋한다. / Change rows-per-page and reset to page 1.
+     *
+     * @param size - 새 페이지당 행 수 / New rows-per-page value
+     */
     setPageSize(size: number): void;
+    /**
+     * 지정 페이지로 이동한다(범위를 벗어나면 클램프). / Navigate to the given page (clamped to valid range).
+     *
+     * @param page - 이동할 페이지 번호(1-base) / Target page number (1-based)
+     */
     goTo(page: number): void;
-    /** 현재 페이지의 [startIndex, endIndex] 반환 (DataLayer 인덱스 기준) */
+    /**
+     * 현재 페이지의 `[startIndex, endIndex]` 반환(DataLayer 인덱스 기준). / Return `[startIndex, endIndex]` for the current page (DataLayer index space).
+     *
+     * @returns 현재 페이지의 시작/끝 인덱스(포함) / Start/end index (inclusive) for the current page
+     */
     getRange(): {
         start: number;
         end: number;
     };
+    /** @internal 현재 상태로 `onChange` 콜백을 실행한다. / Invokes the `onChange` callback with the current state. */
     private _emit;
+    /** @internal 페이지네이션 바 DOM 을 전체 재렌더한다. / Fully re-renders the pagination bar DOM. */
     private _render;
+    /** i18n: 상주 크롬 라벨을 활성 로케일로 다시 그린다(setLocale 경로). / i18n: repaint resident chrome labels in the active locale (setLocale path). */
+    refreshLabels(): void;
+    /** 페이지네이션 바 DOM 을 제거한다. / Remove the pagination bar DOM. */
     destroy(): void;
 }

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,20 +18,39 @@ 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;
     hasCellFormula?: (rowId: string, field: string) => boolean;
     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;
@@ -44,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;
 }