open-grid 1.3.0 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,83 +1,163 @@
1
1
  import { PartialLocaleMessages, LocaleMessageKey, MessageValue } from './i18n/types.js';
2
2
  import { FormulaErrorCode } from './formula/types.js';
3
3
  import { RangeStats as _RangeStats } from './range/RangeQuery.js';
4
- /** 컬럼 데이터 타입. / Column data type. */
4
+ /**
5
+ * 컬럼이 담는 값의 종류. 이 값 하나로 그리드가 "어떻게 정렬하고, 기본 렌더러로 무엇을 쓰고,
6
+ * 편집기를 무엇으로 열지"를 결정합니다. 지정하지 않으면 문자열처럼 다룹니다.
7
+ * / What kind of value a column holds. This single choice drives how the grid sorts, which
8
+ * default renderer it uses, and which editor it opens. Unset behaves like a string.
9
+ *
10
+ * - `'string'` : 일반 텍스트. / Plain text.
11
+ * - `'number'` : 숫자(오른쪽 정렬·숫자 비교·천단위 포맷). / Number (right-aligned, numeric compare, thousand separators).
12
+ * - `'date'` : 날짜(달력 편집기·날짜 비교). / Date (calendar editor, date compare).
13
+ * - `'boolean'` : 참/거짓(체크박스 표시). / True/false (rendered as a checkbox).
14
+ * - `'select'` : 목록에서 하나 선택(드롭다운 편집기). / Single choice from a list (dropdown editor).
15
+ * - `'radio'` : 같은 그룹 안에서 하나 선택. / Single choice within a radio group.
16
+ * - `'img'` : 셀 값을 이미지 주소로 보고 그림 표시. / Treat the value as an image URL and show it.
17
+ * - `'html'` : HTML 문자열을 그대로 렌더(기본 sanitize). / Render an HTML string (sanitized by default).
18
+ * - `'barcode'` : 값을 바코드 그래픽으로 표시. / Show the value as a barcode graphic.
19
+ */
5
20
  export type DataType = 'string' | 'number' | 'date' | 'boolean' | 'select' | 'radio' | 'img' | 'html' | 'barcode';
6
21
  export type { MaskType, MaskDef } from './MaskingEngine.js';
7
- /** 선택 모드('cells' = F1 범위 선택). / Selection mode ('cells' = F1 range selection). */
22
+ /**
23
+ * 사용자가 클릭·드래그로 무엇을 선택할 수 있는지 정하는 모드.
24
+ * / What the user can select by clicking or dragging.
25
+ *
26
+ * - `'single'` : 한 번에 한 행만. / One row at a time.
27
+ * - `'row'` : 행 단위 선택(다중 가능은 UI에 따름). / Row-level selection.
28
+ * - `'multiple'` : 여러 행을 함께(Ctrl/Shift). / Multiple rows together (Ctrl/Shift).
29
+ * - `'cells'` : 스프레드시트처럼 셀 사각형 범위를 선택(채우기 핸들 포함). / Spreadsheet-style rectangular cell range (with fill handle).
30
+ */
8
31
  export type SelectionMode = 'single' | 'row' | 'multiple' | 'cells';
9
- /** 정렬 방향. / Sort direction. */
32
+ /** 정렬 방향. `'asc'` 오름차순(작은 값 먼저), `'desc'` 내림차순(큰 값 먼저). / Sort direction: 'asc' ascending (smallest first), 'desc' descending (largest first). */
10
33
  export type SortDir = 'asc' | 'desc';
11
- /** 삽입 위치(키워드 또는 인덱스). / Insertion position (keyword or index). */
34
+ /**
35
+ * 새 항목을 어디에 끼워 넣을지. 키워드로 상대 위치를 주거나, 숫자로 정확한 인덱스를 줍니다.
36
+ * / Where to insert a new item — a keyword for a relative spot, or a number for an exact index.
37
+ *
38
+ * - `'first'` : 맨 앞. / At the very front.
39
+ * - `'last'` : 맨 뒤. / At the very end.
40
+ * - `'before'` : 기준 위치 바로 앞. / Just before the reference position.
41
+ * - `'after'` : 기준 위치 바로 뒤. / Just after the reference position.
42
+ * - `number` : 해당 인덱스 자리. / At that exact index.
43
+ */
12
44
  export type Position = 'first' | 'last' | 'before' | 'after' | number;
13
45
  /** 내장 셀 렌더러 타입 이름. / Built-in cell renderer type name. */
14
46
  export type RendererType = 'text' | 'number' | 'date' | 'checkbox' | 'button' | 'link' | 'image' | 'icon' | 'switch' | 'sparkline' | 'template' | 'custom' | 'badge' | 'progress' | 'rating' | 'radio' | 'img' | 'html' | 'barcode';
15
47
  /** 내장 셀 에디터 타입 이름. / Built-in cell editor type name. */
16
48
  export type EditorType = 'text' | 'number' | 'date' | 'select' | 'checkbox' | 'custom';
17
49
  /**
18
- * 셀 마우스 이벤트 페이로드(cellClick/cellDblClick/cellMouseOver …).
19
- * / Cell mouse event payload (cellClick/cellDblClick/cellMouseOver …).
50
+ * 사용자가 셀을 마우스로 조작할 때(클릭·더블클릭·마우스 올림 등) 그 핸들러로 전달되는 정보 묶음입니다.
51
+ * "어느 행·어느 컬럼의 어떤 값이, 어떤 DOM 요소에서, 원래 어떤 브라우저 이벤트로" 일어났는지를
52
+ * 한 번에 담아 주므로 핸들러 안에서 좌표를 다시 계산할 필요가 없습니다.
53
+ * / The payload handed to your handler when the user manipulates a cell with the mouse
54
+ * (click / dbl-click / mouse-over …). It bundles which row & column, what value, which DOM
55
+ * element, and the original browser event — so your handler never has to recompute coordinates.
56
+ * 관련 옵션 / Related options: onCellClick, onCellDblClick, onCellMouseOver …
20
57
  *
21
58
  * @typeParam T - 행 데이터 타입 / Row data type
22
59
  */
23
60
  export interface CellEvent<T = any> {
61
+ /** 이벤트 이름('cellClick' 등). / The event name (e.g. 'cellClick'). */
24
62
  type: string;
63
+ /** 대상 행의 화면 표시 순서 인덱스. / Screen-order index of the target row. */
25
64
  rowIndex: number;
65
+ /** 대상 컬럼의 인덱스. / Index of the target column. */
26
66
  columnIndex: number;
67
+ /** 대상 컬럼의 field 이름. / field name of the target column. */
27
68
  field: string;
69
+ /** 그 셀의 원시 값. / Raw value of that cell. */
28
70
  value: any;
71
+ /** 그 행의 데이터 객체 전체. / The full row-data object. */
29
72
  row: T;
73
+ /** 그 컬럼의 정의. / The column's definition. */
30
74
  column: ColumnDef<T>;
75
+ /** 실제 클릭된 셀 DOM 요소. / The actual clicked cell DOM element. */
31
76
  target: HTMLElement;
77
+ /** 브라우저 원본 마우스 이벤트(좌표·수식어 키 등). / The underlying browser mouse event (coords, modifier keys …). */
32
78
  originalEvent: MouseEvent;
33
79
  }
34
80
  /**
35
- * 셀 편집 이벤트 페이로드(editStart/editEnd/editBefore).
36
- * / Cell edit event payload (editStart/editEnd/editBefore).
81
+ * 셀 값 편집의 흐름(편집 시작 → 커밋 직전 → 편집 끝) 각 지점에서 핸들러로 오는 정보입니다.
82
+ * 편집 전 값(oldValue)과 편집 후 값(newValue)을 함께 주므로, 값이 실제로 바뀌었는지 비교하거나
83
+ * 커밋 직전 훅에서 검증 후 되돌릴 수 있습니다.
84
+ * / Delivered at each point in a cell edit (start → just-before-commit → end). It carries both the
85
+ * value before (oldValue) and after (newValue) so you can compare, or validate and veto the commit.
86
+ * 관련 옵션 / Related options: onEditStart, onEditBefore, onEditEnd
37
87
  *
38
88
  * @typeParam T - 행 데이터 타입 / Row data type
39
89
  */
40
90
  export interface EditEvent<T = any> {
91
+ /** 이벤트 이름('editStart'/'editEnd'/'editBefore'). / The event name. */
41
92
  type: string;
93
+ /** 편집 중인 행의 화면 표시 순서 인덱스. / Screen-order index of the row being edited. */
42
94
  rowIndex: number;
95
+ /** 편집 중인 컬럼의 인덱스. / Index of the column being edited. */
43
96
  columnIndex: number;
97
+ /** 편집 중인 컬럼의 field 이름. / field name of the column being edited. */
44
98
  field: string;
99
+ /** 편집 전 값. / Value before the edit. */
45
100
  oldValue: any;
101
+ /** 편집 후 들어온 값. / Value after the edit. */
46
102
  newValue: any;
103
+ /** 편집 중인 행의 데이터 객체. / The row-data object being edited. */
47
104
  row: T;
105
+ /** 편집 중인 컬럼의 정의. / The column's definition. */
48
106
  column: ColumnDef<T>;
49
- /** true 로 바꾸면 편집 커밋 취소. / Set true to cancel the edit commit. */
107
+ /** 편집 커밋 직전(onEditBefore)에 true 로 바꾸면 그 편집을 무효화합니다. / In the pre-commit hook (onEditBefore), set true to reject the edit. */
50
108
  cancel?: boolean;
51
109
  }
52
110
  /**
53
- * 행 마우스 이벤트 페이로드(rowClick/rowDblClick/rowMouseOver …).
54
- * / Row mouse event payload (rowClick/rowDblClick/rowMouseOver …).
111
+ * 셀이 아니라 "행 전체"를 마우스로 조작했을 때(행 클릭·더블클릭·마우스 올림 등) 오는 정보입니다.
112
+ * 컬럼 정보 없이 어느 행인지와 그 행 데이터만 필요할 때 CellEvent 보다 가볍게 씁니다.
113
+ * / Delivered when the user manipulates a whole row (row click / dbl-click / mouse-over …). Lighter
114
+ * than CellEvent for when you only need which row and its data, not the column.
115
+ * 관련 옵션 / Related options: onRowClick, onRowDblClick, onRowMouseOver …
55
116
  *
56
117
  * @typeParam T - 행 데이터 타입 / Row data type
57
118
  */
58
119
  export interface RowEvent<T = any> {
120
+ /** 이벤트 이름('rowClick' 등). / The event name (e.g. 'rowClick'). */
59
121
  type: string;
122
+ /** 대상 행의 화면 표시 순서 인덱스. / Screen-order index of the target row. */
60
123
  rowIndex: number;
124
+ /** 그 행의 데이터 객체 전체. / The full row-data object. */
61
125
  row: T;
126
+ /** 이벤트가 일어난 행 DOM 요소. / The row DOM element where the event occurred. */
62
127
  target: HTMLElement;
128
+ /** 브라우저 원본 마우스 이벤트. / The underlying browser mouse event. */
63
129
  originalEvent: MouseEvent;
64
130
  }
65
131
  /**
66
- * 셀 키보드 이벤트 페이로드(cellKeyDown/cellKeyUp/cellKeyPress).
67
- * / Cell keyboard event payload (cellKeyDown/cellKeyUp/cellKeyPress).
132
+ * 셀에 포커스가 있는 상태에서 키를 눌렀을 때(키 다운·업·프레스) 오는 정보입니다. CellEvent 가 담는
133
+ * 행·컬럼·값에 더해, 눌린 키 이름(key)을 함께 주므로 Enter 이동·Delete 지우기 같은 단축키를 직접 구현할 수 있습니다.
134
+ * / Delivered when a key is pressed while a cell has focus (keydown/keyup/keypress). On top of the
135
+ * row/column/value that CellEvent carries, it adds the pressed `key` name so you can build
136
+ * shortcuts like Enter-to-move or Delete-to-clear.
137
+ * 관련 옵션 / Related options: onCellKeyDown, onCellKeyUp, onCellKeyPress
68
138
  *
69
139
  * @typeParam T - 행 데이터 타입 / Row data type
70
140
  */
71
141
  export interface CellKeyEvent<T = any> {
142
+ /** 이벤트 이름('cellKeyDown' 등). / The event name. */
72
143
  type: string;
144
+ /** 대상 행의 화면 표시 순서 인덱스. / Screen-order index of the target row. */
73
145
  rowIndex: number;
146
+ /** 대상 컬럼의 인덱스. / Index of the target column. */
74
147
  columnIndex: number;
148
+ /** 대상 컬럼의 field 이름. / field name of the target column. */
75
149
  field: string;
150
+ /** 그 셀의 원시 값. / Raw value of that cell. */
76
151
  value: any;
152
+ /** 그 행의 데이터 객체 전체. / The full row-data object. */
77
153
  row: T;
154
+ /** 그 컬럼의 정의. / The column's definition. */
78
155
  column: ColumnDef<T>;
156
+ /** 눌린 키 이름(KeyboardEvent.key: 'Enter','ArrowDown','a' …). / The pressed key name (KeyboardEvent.key). */
79
157
  key: string;
158
+ /** 이벤트가 일어난 셀 DOM 요소. / The cell DOM element where the event occurred. */
80
159
  target: HTMLElement;
160
+ /** 브라우저 원본 키보드 이벤트(수식어 키 등). / The underlying browser keyboard event (modifier keys …). */
81
161
  originalEvent: KeyboardEvent;
82
162
  }
83
163
  /** 정렬 변경 이벤트(sortChange). / Sort change event (sortChange). */
@@ -150,40 +230,56 @@ export interface SelectionEvent<T = any> {
150
230
  cells?: CellRange[];
151
231
  }
152
232
  /**
153
- * 셀 범위(사각형) 좌표. / Cell range (rectangle) coordinates.
233
+ * 선택된 셀들의 사각형 범위를 네 모서리 인덱스로 나타냅니다(엑셀의 A1:C5 같은 개념).
234
+ * 범위 선택 기능이 이 값을 만들어 내고, 수식의 참조 대상과 차트의 데이터 소스가 이 좌표를 그대로 읽어 씁니다.
235
+ * / A rectangular block of selected cells, given as its four corner indexes (think of a spreadsheet's
236
+ * A1:C5). Range selection produces it; cell formulas and chart sources consume the same coordinates.
237
+ *
238
+ * 좌표가 가리키는 것 / What the coordinates mean:
239
+ * - 행 인덱스(startRow/endRow)는 "화면에 보이는 순서"입니다. 그룹·트리의 가상 행이나 펼쳐진 상세 행까지
240
+ * 포함한 순서라서, 정렬·필터만 반영한 순수 데이터 순서와는 다를 수 있습니다.
241
+ * / Row indexes are in on-screen order — they include group/tree pseudo-rows and expanded detail
242
+ * rows, so they can differ from the pure data order that reflects only sort/filter.
243
+ * - 컬럼 인덱스(startCol/endCol)는 "지금 보이는 컬럼들" 기준입니다(숨긴 컬럼 제외). 컬럼을 다시 보이게 하면
244
+ * 재렌더 때 좌표 표시가 갱신됩니다.
245
+ * / Column indexes count only currently visible columns (hidden ones excluded); un-hiding a column
246
+ * refreshes the displayed coordinates on the next render.
154
247
  *
155
- * CellRangeSemantics — CellRange 의미 규범(C0.4, 15_cross_contracts.md). 소유자 = F1(범위 선택).
156
- * / CellRange semantic contract (C0.4, 15_cross_contracts.md). Owner = F1 (range selection).
157
- * F3(수식 ref)·F4(차트 소스)는 이 의미로만 CellRange 를 소비한다.
158
- * - startRow/endRow : flat/visual index (C0.2 — FlatRowModel 이 다루는 화면 표시 순서).
159
- * group/tree pseudo-row, (F2 도입 후) detail head/filler 도 포함한 인덱스 공간이며,
160
- * display index(정렬/필터만 반영, group/tree 제외)와 다르다.
161
- * - startCol/endCol : `ColumnLayout.visibleLeaves` 인덱스(숨김 컬럼 제외). 숨김 컬럼은
162
- * 좌표를 흔들지 않되, 언하이드 시 재렌더로 좌표 표시(A1 등)가 갱신된다.
163
- * - 선택 자체의 영속 정체성은 이 인덱스가 아니라 stable (rowId × field) 앵커로 저장한다
164
- * (C0.5) — CellRange 는 어디까지나 "현재 화면에 투영된" 사각형 표현이다.
248
+ * 주의 / Note: 선택의 "영구 신원"은 이 인덱스가 아니라 안정적인 (행 id × field) 앵커로 저장됩니다.
249
+ * CellRange 는 어디까지나 "지금 화면에 투영된" 사각형 표현입니다.
250
+ * / The persistent identity of a selection is stored as a stable (rowId × field) anchor, not as these
251
+ * indexes — CellRange is only the "currently projected onto screen" rectangle.
165
252
  */
166
253
  export interface CellRange {
254
+ /** 위쪽 경계 행(화면 표시 순서). / Top boundary row (on-screen order). */
167
255
  startRow: number;
256
+ /** 아래쪽 경계 행(화면 표시 순서). / Bottom boundary row (on-screen order). */
168
257
  endRow: number;
258
+ /** 왼쪽 경계 컬럼(보이는 컬럼 기준). / Left boundary column (among visible columns). */
169
259
  startCol: number;
260
+ /** 오른쪽 경계 컬럼(보이는 컬럼 기준). / Right boundary column (among visible columns). */
170
261
  endCol: number;
171
262
  }
172
- /** F1 범위 선택 옵션. / F1 range-selection options. */
263
+ /**
264
+ * 스프레드시트식 범위 선택과 채우기 핸들의 세부 동작을 조절합니다. selection: 'cells' 로 켠 뒤,
265
+ * 채우기 핸들을 보일지·자동 스크롤 폭·시리즈 자동 감지 여부 등을 여기서 미세 조정합니다.
266
+ * / Fine-tunes spreadsheet-style range selection and the fill handle. After enabling selection:
267
+ * 'cells', tweak whether the handle shows, the autoscroll band, series auto-detection, and so on.
268
+ */
173
269
  export interface RangeSelectionOptions {
174
- /** 기본 selection==='cells' 와 동치 / Equivalent to selection==='cells'. Default follows selection. */
270
+ /** 범위 선택 켜기. 생략 시 selection==='cells' 여부를 따릅니다. / Enable range selection. Unset follows whether selection==='cells'. */
175
271
  enabled?: boolean;
176
- /** 기본 true — 핸들 표시/드래그 / Default true — show/drag the fill handle */
272
+ /** 선택 영역 모서리의 채우기 핸들(작은 사각형)을 보이고 드래그할 수 있게 할지. 기본 true. / Show and allow dragging the fill handle (the small corner square). Default true. */
177
273
  fillHandle?: boolean;
178
- /** 기본 false — Ctrl 멀티 rect(Full, 미구현) / Default false — Ctrl multi-rect (Full tier, not implemented) */
274
+ /** Ctrl 로 사각형 여러 개를 동시에 선택하게 할지. 기본 false(아직 미구현). / Whether Ctrl selects several rectangles at once. Default false (not implemented yet). */
179
275
  multiRange?: boolean;
180
- /** 기본 24(px) — autoscroll 밴드 폭 / Default 24(px) — autoscroll edge band width */
276
+ /** 드래그가 이 가장자리 폭(px) 안에 들어오면 화면이 자동으로 스크롤됩니다. 기본 24. / When the drag enters this edge band (px), the view auto-scrolls. Default 24. */
181
277
  autoScrollEdge?: number;
182
- /** 기본 true — false 면 항상 copy(시리즈 감지 비활성) / Default true — false forces copy (disables series detection) */
278
+ /** 1,2,3… 같은 규칙을 자동 감지해 이어 채울지. 기본 true. false 면 항상 단순 복사만 합니다. / Whether to auto-detect series (1,2,3…) and extend them. Default true; false always plain-copies. */
183
279
  seriesFill?: boolean;
184
- /** 기본 false — 그룹/트리 모드 범위선택(MVP 비활성) / Default false — range selection in group/tree mode (off in MVP) */
280
+ /** 그룹·트리 모드에서도 범위 선택을 허용할지. 기본 false(현재 비활성). / Whether range selection also works in group/tree mode. Default false (off for now). */
185
281
  enabledInTreeGroup?: boolean;
186
- /** 기본 false — 수식 대상 덮어쓰기(C3.2 opt-in) / Default false — overwrite formula cells on fill (C3.2 opt-in) */
282
+ /** 채우기가 수식이 들어 있는 셀을 덮어쓰도록 허용할지. 기본 false(수식 보호). / Whether filling may overwrite cells that contain formulas. Default false (formulas protected). */
187
283
  fillOverwriteFormula?: boolean;
188
284
  }
189
285
  /** F1 채우기 커밋 이벤트(onRangeFill). / F1 fill commit event (onRangeFill). */
@@ -212,22 +308,36 @@ export interface RangeChangeEvent {
212
308
  range: CellRange | null;
213
309
  }
214
310
  export type { FormulaErrorCode } from './formula/types.js';
215
- /** F3 셀 수식 옵션(C5.1 단일 중첩 — 최상위 flat 키 금지). / F3 cell-formula options (C5.1 single nesting — no top-level flat keys). */
311
+ /**
312
+ * 셀에 '=' 로 시작하는 수식을 넣어 다른 셀을 참조·계산하게 하는 기능의 세부 설정입니다. 엑셀처럼
313
+ * 셀에 직접 '=A1+B2' 를 입력해 쓰게 할지, 참조를 어떻게 해석할지, 변경 시 자동으로 다시 계산할지 등을 정합니다.
314
+ * / Settings for cell formulas — cells that start with '=' and reference/compute other cells. Decide
315
+ * whether users can type '=A1+B2' directly, how references are interpreted, and whether edits
316
+ * trigger a recompute.
317
+ */
216
318
  export interface FormulaOptions {
217
- /** 셀 수식 인-셀 '=' 편집 자동 인식 on(기본 false — 회귀 0). setCellFormula API 는 이 값과 무관하게 항상 동작. / Auto-recognize in-cell '=' edits (default false — zero regression). setCellFormula always works regardless. */
319
+ /** 셀에 '=' 를 직접 입력하면 수식으로 자동 인식할지. 기본 false(끄면 기존 편집과 동일). setCellFormula API 로는 이 값과 상관없이 언제나 수식을 넣을 수 있습니다. / Whether typing '=' in a cell is auto-recognized as a formula. Default false; the setCellFormula API works regardless. */
218
320
  enabled?: boolean;
219
- /** 참조 정규화 정책(기본 'stable', §3.2). / Reference normalization policy (default 'stable', §3.2). */
321
+ /**
322
+ * 참조를 어떻게 기억할지. 'stable'(기본)은 행을 정렬·이동해도 같은 셀을 계속 가리키고,
323
+ * 'relative'는 위치 기준(엑셀 A1 상대참조처럼)입니다.
324
+ * / How references are anchored. 'stable' (default) keeps pointing at the same cell even after
325
+ * sorting/moving rows; 'relative' is position-based (like a spreadsheet's relative A1 ref).
326
+ */
220
327
  refMode?: 'stable' | 'relative';
221
- /** 나눗셈 소수 자리(기본 30, FormulaEngine 계승). / Division decimal precision (default 30, inherited from FormulaEngine). */
328
+ /** 나눗셈 결과의 소수점 자리수. 기본 30. / Decimal precision for division results. Default 30. */
222
329
  divisionPrecision?: number;
223
- /** 수식 바 표시(P1, 기본 false — 미구현). / Formula bar (P1, default false — not implemented). */
330
+ /** 상단 수식 입력 바를 보일지. 기본 false(아직 미구현). / Whether to show a top formula bar. Default false (not implemented yet). */
224
331
  formulaBar?: boolean;
225
- /** 수식 셀 마커(기본 true — HANMS-09/R-FORMULA-MARKER). / Formula cell marker (default true). */
332
+ /** 수식이 든 셀에 표식(마커)을 달아 구분해 줄지. 기본 true. / Whether to mark formula-bearing cells so they stand out. Default true. */
226
333
  cellMarker?: boolean;
227
- /** 편집 시 자동 재계산(기본 true). / Auto recalc on edit (default true). */
334
+ /** 참조된 셀이 바뀌면 수식을 자동으로 다시 계산할지. 기본 true. / Whether editing a referenced cell auto-recomputes the formula. Default true. */
228
335
  autoRecalc?: boolean;
336
+ /** 어떤 셀의 수식 자체가 바뀌었을 때 호출. / Fired when a cell's formula text itself changes. */
229
337
  onFormulaChange?: (e: FormulaChangeEvent) => void;
338
+ /** 재계산이 끝났을 때 호출(무엇이 바뀌었고 얼마나 걸렸는지). / Fired after a recompute finishes (what changed, how long it took). */
230
339
  onFormulaRecalc?: (e: FormulaRecalcEvent) => void;
340
+ /** 수식 계산 중 오류(순환 참조·0 나눗셈 등)가 났을 때 호출. / Fired on a formula error (circular ref, divide-by-zero …). */
231
341
  onFormulaError?: (e: FormulaErrorEvent) => void;
232
342
  }
233
343
  /** F3 수식 변경 이벤트(onFormulaChange). / F3 formula change event (onFormulaChange). */
@@ -243,7 +353,7 @@ export interface FormulaRecalcEvent {
243
353
  changed: string[];
244
354
  cycles: number;
245
355
  ms: number;
246
- /** Spike-A §8 교훈: 폐포가 임계(500) 초과 시 true(가이드 문서화/모니터링용). / true when the dirty closure exceeded the threshold (500) — for docs/monitoring. */
356
+ /** 이번에 다시 계산해야 했던 셀 무리가 임계값(500)을 넘었으면 true. 성능 모니터링·경고용 신호입니다. / true when the recalculated cell set exceeded the threshold (500) — a signal for perf monitoring/warnings. */
247
357
  large: boolean;
248
358
  }
249
359
  /** F3 수식 오류 이벤트(onFormulaError). / F3 formula error event (onFormulaError). */
@@ -253,96 +363,151 @@ export interface FormulaErrorEvent {
253
363
  error: FormulaErrorCode;
254
364
  }
255
365
  export type { RangeStats } from './range/RangeQuery.js';
256
- /** masterDetail.renderer 3번째 인자(§6.1). / Third argument of masterDetail.renderer (§6.1). */
366
+ /**
367
+ * 상세 패널을 직접 그릴 때(renderer) 세 번째 인자로 받는 도우미 묶음입니다. 방금 펼쳐진 행의 정보와,
368
+ * 그 패널을 접거나 다시 재는 조작을 담고 있어 커스텀 패널 안에서 그리드를 되짚을 수 있습니다.
369
+ * / The helper bundle passed as the 3rd argument when you draw a detail panel yourself (renderer). It
370
+ * carries the just-expanded row's info plus actions to collapse or re-measure the panel, so your
371
+ * custom panel can reach back into the grid.
372
+ */
257
373
  export interface DetailRenderApi<T = any> {
374
+ /** 이 패널을 소유한 그리드 인스턴스. / The grid instance owning this panel. */
258
375
  grid: OpenGridInstance<T>;
376
+ /** 펼쳐진 행의 안정적 id. / Stable id of the expanded row. */
259
377
  rowId: string;
260
- /** 현재 그리드의 중첩 깊이(CON-4). 0 = 최상위. / Nesting depth of this grid (CON-4). 0 = top level. */
378
+ /** 이 그리드가 몇 겹째 중첩인지. 0 = 최상위. / How deeply nested this grid is. 0 = top level. */
261
379
  depth: number;
262
- /** 이 패널을 접는다. / Collapse this panel. */
380
+ /** 이 패널을 접습니다. / Collapse this panel. */
263
381
  collapse: () => void;
264
- /** 패널 재측정(Phase2 auto 대비 자리 — MVP 는 no-op 에 가까움). / Re-measure the panel (placeholder for Phase 2 auto; near no-op in MVP). */
382
+ /** 패널 크기를 다시 잽니다. / Re-measure the panel. */
265
383
  refresh: () => void;
266
384
  }
267
- /** F2 마스터/디테일 옵션(C5.1 단일 중첩 — 구 flat `detail*`/`masterDetail:boolean` 은 이 안으로 접힘). / F2 master/detail options (C5.1 single nesting — legacy flat `detail*`/`masterDetail:boolean` folded in here). */
385
+ /**
386
+ * 각 행을 펼치면 그 아래에 딸린 상세 패널이 열리는 마스터/디테일 기능의 설정입니다. 주문 목록에서 한 줄을
387
+ * 열면 주문 상세가, 부서 목록에서 한 줄을 열면 소속 직원 표가 펼쳐지는 식입니다. 패널 내용은 두 가지 방법으로
388
+ * 채웁니다 — 직접 HTML 을 그리는 renderer 를 주거나, 자식 그리드를 자동 생성하는 subgridOptions 를 줍니다.
389
+ * / Master/detail: expanding a row opens an attached detail panel beneath it — open an order to see
390
+ * its lines, open a department to see its staff. Fill the panel either by drawing HTML yourself
391
+ * (renderer) or by auto-creating a child grid (subgridOptions).
392
+ */
268
393
  export interface MasterDetailOptions<T = any> {
269
- /** 기능 on/off. 기본 false. / Feature on/off. Default false. */
394
+ /** 기능 켜기/끄기. 기본 false(꺼짐). / Turn the feature on/off. Default false (off). */
270
395
  enabled?: boolean;
271
- /** 임의 HTML/컴포넌트를 host 에 주입(§5). subgridOptions 와 동시 지정 시 이 쪽이 우선. / Inject arbitrary HTML/components into the host (§5). Takes precedence over subgridOptions. */
396
+ /** 패널 안을 직접 그리는 함수(host 요소에 HTML/컴포넌트 주입). subgridOptions 와 같이 주면 이쪽이 우선. / A function that draws the panel yourself (inject HTML/components into host). Wins over subgridOptions if both given. */
272
397
  renderer?: (row: T, host: HTMLElement, api: DetailRenderApi<T>) => void | HTMLElement;
273
- /** 패널 높이(px). 기본 200. MVP 는 rowHeight 배수로 양자화(EC-10). / Panel height (px). Default 200. Quantized to rowHeight multiples in MVP (EC-10). */
398
+ /** 패널의 세로 높이(px). 기본 200. 현재는 행 높이의 배수로 맞춰집니다. / Panel height (px). Default 200. Currently snapped to a multiple of the row height. */
274
399
  height?: number;
275
400
  /**
276
- * 'fixed'(기본)만 MVP 에서 동작. 'auto' 는 Spike-B(C12.2) 통과 전 미공개 — 지정해도
277
- * DetailManager 가 'fixed' 로 무시 처리하고 1회 console.warn 한다.
278
- * / Only 'fixed' (default) works in MVP. 'auto' is unreleased until Spike-B (C12.2) passes —
279
- * if specified, DetailManager treats it as 'fixed' and warns once.
401
+ * 패널 높이를 어떻게 정할지. 'fixed'(기본)만 지금 동작합니다. 'auto'(내용에 맞춰 자동)는 아직 미공개라,
402
+ * 지정해도 'fixed' 로 처리되고 한 번 경고를 남깁니다.
403
+ * / How the panel height is decided. Only 'fixed' (default) works today. 'auto' (fit-to-content) is
404
+ * not released yet — if set, it's treated as 'fixed' and warns once.
280
405
  */
281
406
  heightMode?: 'fixed' | 'auto';
282
- /** 기본 true. false = 아코디언(펼침 1개만 허용). / Default true. false = accordion (only one panel open). */
407
+ /** 여러 행을 동시에 펼쳐 둘지. 기본 true. false 로 하면 아코디언처럼 한 번에 하나만 열립니다. / Whether several rows can stay open at once. Default true; false = accordion (one open at a time). */
283
408
  expandMultiple?: boolean;
284
- /** 기본 false. true 면 collapse 해도 host/instance 캐시를 유지(재펼침 시 재생성 생략). / Default false. true keeps host/instance cache across collapse (skips re-creation on re-expand). */
409
+ /** true 면 접어도 패널 내용을 캐시로 남겨 다시 펼칠 때 재생성을 건너뜁니다. 기본 false. / true keeps the panel cached when collapsed, skipping rebuild on re-expand. Default false. */
285
410
  cache?: boolean;
286
- /** 어포던스 위치. 기본 'expander-col'(전용 컬럼). / Toggle affordance position. Default 'expander-col' (dedicated column). */
411
+ /** 펼침/접힘 버튼을 어디에 둘지. 기본 'expander-col'(전용 컬럼). 'first-cell'=첫 셀 안. / Where the expand toggle sits. Default 'expander-col' (a dedicated column); 'first-cell' = inside the first cell. */
287
412
  toggle?: 'expander-col' | 'first-cell';
288
- /** 패널 role=region 의 aria-label. 기본 '상세 내용'. / aria-label of the panel region. Default '상세 내용'. */
413
+ /** 스크린리더가 읽을 패널 영역 이름. 기본 '상세 내용'. / The panel region's screen-reader label. Default '상세 내용' (Details). */
289
414
  ariaLabel?: string;
290
- /** 중첩 깊이 한계(CON-4/FR-10). 기본 2. / Nesting depth limit (CON-4/FR-10). Default 2. */
415
+ /** 패널 안에 또 패널을 열 수 있는 최대 겹수. 기본 2. / How many levels of nested panels are allowed. Default 2. */
291
416
  maxDepth?: number;
292
- /** 지정 시 height 대신 이 값을 슬롯수(정수, 최소 1)로 직접 사용. / When set, used directly as slot count (integer, min 1) instead of height. */
417
+ /** 지정하면 height(px) 대신 "행 몇 개 높이"(정수, 최소 1)로 패널 높이를 정합니다. / When set, sizes the panel by row-count (integer, min 1) instead of height(px). */
293
418
  detailRowCount?: number;
294
- /** renderer 미지정 시: 자식 OpenGrid 를 이 옵션으로 자동 생성(§5 ②). / When renderer is absent: auto-create a child OpenGrid with these options (§5 ②). */
419
+ /** renderer 를 안 줬을 때, 이 옵션으로 자식 그리드를 자동 생성해 패널을 채웁니다. / When no renderer is given, auto-create a child grid from these options to fill the panel. */
295
420
  subgridOptions?: GridOptions<any>;
296
421
  }
297
- /** rowExpand/rowCollapse 페이로드(C5.2, §6.3). / rowExpand/rowCollapse payload (C5.2, §6.3). */
422
+ /**
423
+ * 행 상세 패널이 펼쳐지거나(rowExpand) 접힐 때(rowCollapse) 핸들러로 오는 정보입니다.
424
+ * 어느 행인지와, 그 상세 패널이 붙은 DOM 요소(host)를 함께 줍니다.
425
+ * / Delivered when a row's detail panel expands (rowExpand) or collapses (rowCollapse). It tells you
426
+ * which row it was and the DOM element (host) the detail panel is attached to.
427
+ */
298
428
  export interface RowExpandEvent<T = any> {
299
- /** flat/visual index(C0.2). */
429
+ /** 대상 행의 화면 표시 순서 인덱스. / Screen-order index of the target row. */
300
430
  rowIndex: number;
431
+ /** 대상 행의 안정적 id. / Stable id of the target row. */
301
432
  rowId: string;
433
+ /** 그 행의 데이터 객체. / The row-data object. */
302
434
  row: T;
435
+ /** 상세 패널이 붙은 DOM 요소(접힘 이벤트에서는 null 일 수 있음). / The DOM element the detail panel is attached to (may be null on collapse). */
303
436
  host: HTMLElement | null;
304
437
  }
305
- /** 셀 렌더러 상세 지정(type + 렌더러별 부가 옵션). / Detailed cell renderer spec (type + renderer-specific extras). */
438
+ /**
439
+ * 셀을 어떻게 그릴지 자세히 지정합니다. 렌더러 타입 이름만으로 부족해 부가 설정까지 주고 싶을 때
440
+ * 씁니다(`column.renderer` 에 문자열 대신 이 객체를 넘김). `type` 이외의 키는 렌더러마다 다르게 해석됩니다.
441
+ * / Detailed spec for how a cell is drawn. Use it (instead of a bare renderer-type string in
442
+ * `column.renderer`) when the renderer needs extra settings. Keys beyond `type` are
443
+ * renderer-specific.
444
+ */
306
445
  export interface RendererDef {
446
+ /** 사용할 내장 렌더러 이름. / Which built-in renderer to use. */
307
447
  type: RendererType;
448
+ /** 렌더러별 추가 옵션(자유 키). / Renderer-specific extra options (free-form keys). */
308
449
  [key: string]: any;
309
450
  }
310
- /** 셀 에디터 상세 지정(type + 에디터별 부가 옵션). / Detailed cell editor spec (type + editor-specific extras). */
451
+ /**
452
+ * 편집기를 어떻게 열지 자세히 지정합니다. 예를 들어 `select` 편집기에 선택지 목록을,
453
+ * `number` 편집기에 최소·최대·증가폭을 함께 줄 때 씁니다(`column.editor` 에 이 객체를 넘김).
454
+ * / Detailed spec for how the editor opens — e.g. a `select` editor's choices, or a `number`
455
+ * editor's min/max/step (passed to `column.editor`).
456
+ */
311
457
  export interface EditorDef {
458
+ /** 사용할 내장 편집기 이름. / Which built-in editor to use. */
312
459
  type: EditorType;
460
+ /** select 편집기의 선택지(문자열 또는 {label,value}). / Choices for a select editor. */
313
461
  options?: Array<string | {
314
462
  label: string;
315
463
  value: any;
316
464
  }>;
465
+ /** select 에서 다중 선택 허용. / Allow multiple selection in select. */
317
466
  multiple?: boolean;
467
+ /** number 편집기의 최솟값. / Minimum for a number editor. */
318
468
  min?: number;
469
+ /** number 편집기의 최댓값. / Maximum for a number editor. */
319
470
  max?: number;
471
+ /** number 편집기의 증가 단위. / Step increment for a number editor. */
320
472
  step?: number;
473
+ /** 입력값 포맷 문자열. / Format string for the input value. */
321
474
  format?: string;
475
+ /** 빈 편집기에 보일 안내 문구. / Placeholder shown in an empty editor. */
322
476
  placeholder?: string;
477
+ /** 편집기별 추가 옵션(자유 키). / Editor-specific extra options (free-form keys). */
323
478
  [key: string]: any;
324
479
  }
325
480
  /**
326
- * 컬럼 정의. / Column definition.
481
+ * 컬럼 한 개를 어떻게 보이고 동작하게 할지 담는 설정 뭉치입니다. 그리드는 `columns` 배열에 담긴 이
482
+ * 정의들을 왼쪽부터 순서대로 그립니다. 최소한 `field`(어떤 데이터를 보여줄지)와 `header`(머리글 글자)만
483
+ * 있으면 되고, 나머지는 필요할 때만 켜는 선택 항목입니다.
484
+ * / The settings bundle for a single column — what it shows and how it behaves. The grid draws the
485
+ * definitions in the `columns` array left to right. Only `field` (which data to show) and `header`
486
+ * (the caption) are required; everything else is opt-in.
327
487
  *
328
488
  * @typeParam T - 행 데이터 타입 / Row data type
329
489
  * @example
330
490
  * const col: ColumnDef = { field: 'price', header: '가격', type: 'number', format: '#,##0' };
331
491
  */
332
492
  export interface ColumnDef<T = any> {
333
- /** 행 객체의 속성 키(고유). / Property key on the row object (unique). */
493
+ /** 이 컬럼이 읽어 올 행 객체의 속성 이름(예: 행이 `{price: 1000}` 이면 `'price'`). 컬럼마다 고유. / The row-object property this column reads (e.g. `'price'` for a row `{price: 1000}`). Unique per column. */
334
494
  field: string;
335
- /** 헤더 표시 텍스트('\n' 은 줄바꿈). / Header caption ('\n' breaks lines). */
495
+ /** 머리글에 보일 글자. 문자열 안의 '\n' 은 두 줄로 나뉩니다. / The caption shown in the header. A '\n' inside splits into two lines. */
336
496
  header: string;
337
- /** 고정 폭(px). / Fixed width (px). */
497
+ /** 이 폭(px)으로 고정. 지정하면 flex 를 무시하고 정확히 이 값이 됩니다. / Pin this width (px). When set it overrides flex and stays exactly this. */
338
498
  width?: number;
339
- /** 최소 폭(px). / Minimum width (px). */
499
+ /** 줄어들 때 넘지 않을 최소 폭(px). / Lower bound (px) the column won't shrink past. */
340
500
  minWidth?: number;
341
- /** 최대 폭(px). / Maximum width (px). */
501
+ /** 늘어날 때 넘지 않을 최대 폭(px). / Upper bound (px) the column won't grow past. */
342
502
  maxWidth?: number;
343
- /** 잔여 폭 배분 가중치. / Flex weight for remaining width distribution. */
503
+ /** 남는 가로 공간을 컬럼끼리 나눌 때의 비율. 값이 클수록 더 많이 차지합니다(width 미지정 컬럼끼리). / Weight for sharing leftover horizontal space — higher takes more (among columns without width). */
344
504
  flex?: number;
345
- /** 데이터 타입(정렬·기본 렌더러 결정). / Data type (drives sorting & default renderer). */
505
+ /**
506
+ * 이 컬럼 값의 종류. 이걸 정하면 그에 맞는 정렬 방식과 기본 렌더러가 자동으로 붙습니다
507
+ * (예: 'number' 는 오른쪽 정렬 + 숫자 비교). 지정하지 않으면 문자열처럼 다룹니다.
508
+ * / The kind of value here. Setting it auto-wires the matching sort behavior and default renderer
509
+ * (e.g. 'number' → right-aligned + numeric compare). Unset behaves like a string.
510
+ */
346
511
  type?: DataType;
347
512
  /**
348
513
  * 숫자/날짜 포맷 문자열. 숫자는 통화 기호 접두·접미와 음수 패턴 지원:
@@ -353,13 +518,18 @@ export interface ColumnDef<T = any> {
353
518
  format?: string;
354
519
  /** ISO 통화코드('KRW'|'USD'|'EUR'…). 지정 시 Intl.NumberFormat 로케일 통화 포맷 (format 보다 우선) / ISO currency code; uses Intl.NumberFormat locale currency formatting (takes precedence over format) */
355
520
  currency?: string;
356
- /** 값 → 표시 텍스트 매핑. / Raw value → display text map. */
521
+ /** 저장된 코드값을 사람이 읽는 말로 바꿔 보여줄 때(예: `{ 'M': '남', 'F': '여' }`). / Show human-readable text for stored codes (e.g. `{ 'M':'Male', 'F':'Female' }`). */
357
522
  valueMap?: Record<string, string>;
358
- /** 셀 렌더러(내장 타입명 또는 상세 정의). / Cell renderer (built-in type name or detailed def). */
523
+ /** 셀을 그리는 방식. 내장 렌더러 이름 한 줄로 주거나, 부가 옵션이 필요하면 RendererDef 객체로 줍니다. / How the cell is drawn — a built-in renderer name, or a RendererDef object when extras are needed. */
359
524
  renderer?: RendererType | RendererDef;
360
- /** 편집 가능 여부(불리언 또는 행별 함수). / Editable flag (boolean or per-row function). */
525
+ /**
526
+ * 이 컬럼을 편집할 수 있는지. true 면 항상 편집 가능, 함수로 주면 행마다 다르게 결정합니다
527
+ * (예: 상태가 '확정'인 행만 잠그기). GridOptions.editable 과 둘 다 참일 때만 실제로 열립니다.
528
+ * / Whether this column is editable. true = always; a function decides per row (e.g. lock only
529
+ * 'finalized' rows). Editing opens only when this AND GridOptions.editable are true.
530
+ */
361
531
  editable?: boolean | ((row: T, rowIndex: number) => boolean);
362
- /** 셀 에디터(내장 타입명 또는 상세 정의). / Cell editor (built-in type name or detailed def). */
532
+ /** 편집기 종류. 내장 편집기 이름 한 줄로 주거나, 선택지·최소/최대 등이 필요하면 EditorDef 객체로 줍니다. / The editor — a built-in editor name, or an EditorDef object for choices/min/max, etc. */
363
533
  editor?: EditorType | EditorDef;
364
534
  /** 셀 정렬. / Cell text alignment. */
365
535
  align?: 'left' | 'center' | 'right';
@@ -369,15 +539,15 @@ export interface ColumnDef<T = any> {
369
539
  cellStyle?: CSSProperties | ((value: any, row: T, rowIndex: number) => CSSProperties);
370
540
  /** 헤더 인라인 스타일. / Header inline style. */
371
541
  headerStyle?: CSSProperties;
372
- /** 헤더 클릭 정렬 허용. / Allow sort on header click. */
542
+ /** 이 컬럼 머리글을 클릭하면 정렬되게 할지. 특정 컬럼만 정렬을 막거나 허용할 때 씁니다. / Whether clicking this header sorts. Use it to allow/deny sorting per column. */
373
543
  sortable?: boolean;
374
- /** 필터 아이콘/패널 허용. / Allow the filter icon/panel. */
544
+ /** 이 컬럼에 필터 아이콘·패널을 띄울지. / Whether to show the filter icon/panel on this column. */
375
545
  filterable?: boolean;
376
- /** 헤더 드래그 폭 조절 허용. / Allow header drag resize. */
546
+ /** 머리글 경계를 드래그해 폭을 조절하게 할지. / Whether the user can drag the header edge to resize. */
377
547
  resizable?: boolean;
378
- /** 컬럼 숨김. / Hide the column. */
548
+ /** true 면 이 컬럼을 화면에서 감춥니다(데이터는 남고 showColumn 으로 다시 보임). / true hides the column (data stays; showColumn brings it back). */
379
549
  hidden?: boolean;
380
- /** 왼쪽 고정(frozen) 여부. / Freeze the column to the left. */
550
+ /** true 면 가로 스크롤과 무관하게 왼쪽에 붙박아 둡니다(핵심 식별 컬럼 고정용). / true pins the column to the left regardless of horizontal scroll (for key identifier columns). */
381
551
  frozen?: boolean;
382
552
  /** 셀 줄바꿈: true 면 nowrap+ellipsis 대신 여러 줄로 표시(rowHeight 확대와 함께 사용) / Cell wrapping: true renders multiple lines instead of nowrap+ellipsis (use with a larger rowHeight) */
383
553
  wrap?: boolean;
@@ -416,13 +586,13 @@ export interface ColumnDef<T = any> {
416
586
  sanitize?: boolean;
417
587
  /** barcode — 바코드 높이(px), 기본 28 / barcode — bar height in px, default 28 */
418
588
  barcodeHeight?: number;
419
- /** F4: 표시 소수점 자리수 (display + kahanSum) / F4: display decimal places (display + kahanSum) */
589
+ /** 표시할 때 반올림해서 보여줄 소수점 자리수(합계 계산에도 반영). / Decimal places to show (also applied to summing). */
420
590
  precision?: number;
421
- /** 컬럼 수식(함수식 또는 '[field]' 문자열식). / Column formula (function form or '[field]' string form). */
591
+ /** 이 컬럼 값을 다른 컬럼으로 자동 계산. 함수식 또는 '[field]' 를 쓰는 문자열식. / Auto-compute this column from others — a function, or a string using '[field]' refs. */
422
592
  formula?: string | ((row: T, D: any) => any);
423
- /** 나눗셈 소수점 자리수 (기본 30) / Division decimal precision (default 30) */
593
+ /** 수식 나눗셈의 소수점 자리수. 기본 30. / Decimal precision for division inside the formula. Default 30. */
424
594
  formulaPrecision?: number;
425
- /** 마스킹 타입 또는 상세 정의. / Mask type or detailed mask definition. */
595
+ /** 이 컬럼 값을 가려 표시할 마스킹 타입 또는 상세 정의. / Mask type or detailed definition to obscure this column's values. */
426
596
  mask?: import('./MaskingEngine.js').MaskType | import('./MaskingEngine.js').MaskDef;
427
597
  /** 트리 노드 아이콘(정적 정의 또는 행별 함수). / Tree node icon (static def or per-row function). */
428
598
  treeNodeIcon?: TreeNodeIconDef | ((row: T, hasChildren: boolean, expanded: boolean) => string);
@@ -447,16 +617,32 @@ export interface TreeNodeIconDef {
447
617
  leaf?: string;
448
618
  }
449
619
  type CSSProperties = Partial<Record<keyof CSSStyleDeclaration, string>>;
450
- /** 정렬 항목(멀티정렬 배열 원소). / Sort entry (element of a multi-sort list). */
620
+ /**
621
+ * "이 컬럼을 이 방향으로 정렬" 한 건을 나타냅니다. 여러 개를 배열로 넘기면 앞에 있는 것이 1차 기준,
622
+ * 그 값이 같을 때 다음 것이 2차 기준이 되는 다중 정렬이 됩니다(예: 부서 오름차순 → 급여 내림차순).
623
+ * / One "sort this column this way" entry. Passed as an array, the first is the primary key and later
624
+ * entries break ties — i.e. multi-column sort (e.g. dept asc, then salary desc).
625
+ */
451
626
  export interface SortItem {
627
+ /** 정렬 기준 컬럼의 field. / field of the column to sort by. */
452
628
  field: string;
629
+ /** 정렬 방향. / Sort direction. */
453
630
  dir: SortDir;
454
631
  }
455
- /** 필터 조건 1건. / A single filter condition. */
632
+ /**
633
+ * 필터 한 줄 = "연산자 + 비교값". 예: `{ operator: '>=', value: 1000 }` 는 값이 1000 이상인 행만 남깁니다.
634
+ * 한 컬럼에 여러 조건을 배열로 걸 수 있습니다(모두 만족하는 행만 통과).
635
+ * / One filter clause = "operator + value". e.g. `{ operator: '>=', value: 1000 }` keeps rows whose
636
+ * value is at least 1000. Multiple clauses per column combine (a row must satisfy all).
637
+ */
456
638
  export interface FilterItem {
457
- /** 비교 연산자. / Comparison operator. */
639
+ /**
640
+ * 비교 방식. `'='`·`'!='`·`'>'`·`'>='`·`'<'`·`'<='` 는 값 비교, `'contains'`·`'startsWith'`·`'endsWith'`
641
+ * 는 텍스트 부분 일치입니다. / How to compare — the six symbols are value comparisons; the three
642
+ * word operators are text substring matches.
643
+ */
458
644
  operator: '=' | '!=' | '>' | '>=' | '<' | '<=' | 'contains' | 'startsWith' | 'endsWith';
459
- /** 비교 값. / Comparison value. */
645
+ /** 비교 기준 값. / The value to compare against. */
460
646
  value: any;
461
647
  }
462
648
  /** 집계 연산자. / Aggregate operator. */
@@ -467,28 +653,38 @@ export interface SummaryFieldDef {
467
653
  op: SummaryOp;
468
654
  label?: string;
469
655
  }
470
- /** 그룹 소계/합계 행 옵션. / Group summary row options. */
656
+ /**
657
+ * 그룹마다 소계/합계 행을 자동으로 끼워 넣는 설정입니다. groupBy 로 묶은 각 그룹의 지정 필드를
658
+ * 합·평균 등으로 집계해 그룹 위나 아래에 요약 행으로 보여 줍니다.
659
+ * / Auto-inserts a subtotal/summary row per group. For each group made by groupBy it aggregates the
660
+ * chosen fields (sum, average …) and shows the result as a summary row above or below the group.
661
+ */
471
662
  export interface SummaryOptions {
472
- /** 집계 대상 필드. / Fields to aggregate. */
663
+ /** 집계할 컬럼들의 field 목록. / field names of the columns to aggregate. */
473
664
  fields: string[];
474
- /** 적용 연산(단일 또는 배열). / Operator(s) to apply. */
665
+ /** 어떤 집계를 적용할지(하나 또는 여러 개). 생략 시 기본 동작. / Which aggregate(s) to apply (one or several). */
475
666
  ops?: SummaryOp | SummaryOp[];
476
- /** 소계 행 위치. / Summary row position. */
667
+ /** 요약 행을 그룹 위('top')에 둘지 아래('bottom')에 둘지. / Put the summary row above ('top') or below ('bottom') the group. */
477
668
  position?: 'top' | 'bottom';
478
- /** 다중 소계 행 정의(커스텀 함수 지원). / Multiple summary rows (custom function supported). */
669
+ /** 한 그룹에 요약 행을 여러 줄 만들 때(예: 합계 줄 + 평균 줄). customFn 으로 직접 집계도 가능. / Multiple summary rows per group (e.g. a sum row + an average row); customFn allows your own aggregation. */
479
670
  rows?: Array<{
480
671
  op: SummaryOp;
481
672
  label?: string;
482
673
  customFn?: (items: any[]) => number;
483
674
  }>;
484
675
  }
485
- /** 푸터 셀 정의. / Footer cell definition. */
676
+ /**
677
+ * 그리드 맨 아래(또는 위) 고정 푸터의 셀 한 칸을 정의합니다. 스크롤과 무관하게 늘 보이는 합계 줄을
678
+ * 만들 때 씁니다. `field`+`op` 를 주면 그 컬럼을 집계해 표시하고, `label` 만 주면 고정 문구를 표시합니다.
679
+ * / Defines one cell of the pinned footer (bottom or top) — an always-visible totals row that stays
680
+ * put while the body scrolls. Give `field`+`op` to aggregate a column, or `label` for fixed text.
681
+ */
486
682
  export interface FooterDef {
487
- /** 집계 대상 필드. / Field to aggregate. */
683
+ /** 집계할 컬럼의 field(집계 셀일 때). / field of the column to aggregate (for an aggregate cell). */
488
684
  field?: string;
489
- /** 집계 연산. / Aggregate operator. */
685
+ /** 어떤 집계를 낼지(SUM/AVG/…). / Which aggregate to compute (SUM/AVG/…). */
490
686
  op?: SummaryOp;
491
- /** 라벨 텍스트(집계 대신 표시). / Label text (shown instead of an aggregate). */
687
+ /** 집계 대신 그대로 보여줄 고정 문구(예: '합계'). / Fixed text shown instead of an aggregate (e.g. 'Total'). */
492
688
  label?: string;
493
689
  /**
494
690
  * 숫자 포맷 문자열
@@ -512,27 +708,33 @@ export interface PrintOptions {
512
708
  }
513
709
  /** 내보내기 스타일 모드. / Export style mode. */
514
710
  export type ExportStyleMode = 'theme' | 'none' | 'custom';
515
- /** Excel/CSV/JSON 내보내기 옵션. / Excel/CSV/JSON export options. */
711
+ /**
712
+ * 그리드 내용을 Excel·CSV·JSON 파일로 내보낼 때의 세부 설정입니다. 아무것도 안 주면 기본값으로 곧장
713
+ * 내보내지고, 파일명·시트명·제외 컬럼·제목 행 등을 필요할 때만 얹습니다. 문자열 하나만 넘기면 파일명으로 해석됩니다.
714
+ * / Settings for exporting the grid to Excel/CSV/JSON. With nothing set it exports with defaults;
715
+ * add filename, sheet name, excluded columns, title rows, etc. only as needed. A lone string is
716
+ * treated as the filename.
717
+ */
516
718
  export interface ExportOptions {
517
- /** 저장 파일명. / Output filename. */
719
+ /** 저장될 파일 이름. / The saved file's name. */
518
720
  filename?: string;
519
- /** 엑셀 시트명. / Excel sheet name. */
721
+ /** 엑셀 시트 탭 이름. / Excel sheet tab name. */
520
722
  sheetName?: string;
521
- /** 헤더 행 포함(기본 true). / Include the header row (default true). */
723
+ /** 머리글 행을 포함할지. 기본 true. / Whether to include the header row. Default true. */
522
724
  includeHeader?: boolean;
523
- /** 제외할 필드 목록. / Fields to exclude. */
725
+ /** 내보내기에서 뺄 컬럼들의 field. / field names of columns to leave out. */
524
726
  exceptFields?: string[];
525
- /** 데이터 위에 추가할 제목 행들. / Extra title rows above the data. */
727
+ /** 데이터 위에 얹을 제목 행들(보고서 머리말 등). / Extra title rows placed above the data (report headings, etc.). */
526
728
  headers?: ExportHeaderRow[];
527
- /** 데이터 아래에 추가할 행들. / Extra rows below the data. */
729
+ /** 데이터 아래에 붙일 행들(비고·서명란 등). / Extra rows appended below the data (notes, sign-off …). */
528
730
  footers?: ExportHeaderRow[];
529
- /** F1: CSS 테마 적용 방식 (기본: 'theme') / F1: theme styling mode (default 'theme') */
731
+ /** 내보낸 파일에 그리드 테마 색을 입힐지 방식. 기본 'theme'(현재 테마 반영). / How to style the exported file — default 'theme' (carry the current theme). */
530
732
  styleMode?: ExportStyleMode;
531
- /** true 시 마스킹 활성 컬럼의 값을 마스킹된 형태로 내보냄 (기본: false = 원본 값) / true exports masked values for masked columns (default false = raw values) */
733
+ /** true 면 마스킹된 컬럼을 가려진 상태 그대로 내보냅니다. 기본 false = 원본 값 내보냄. / true exports masked columns still obscured. Default false = raw values. */
532
734
  maskOnExport?: boolean;
533
- /** 내보내기 직전 훅. / Hook just before export. */
735
+ /** 내보내기 시작 직전에 부를 훅(로딩 표시 등). / A hook called just before export starts (show a spinner …). */
534
736
  onBefore?: () => void | Promise<void>;
535
- /** 내보내기 완료 훅(blob 수신). / Hook after export (receives the blob). */
737
+ /** 내보내기 완료 후 부를 훅. 만들어진 파일 blob 을 받습니다. / A hook called after export, receiving the produced file blob. */
536
738
  onAfter?: (blob: Blob) => void;
537
739
  }
538
740
  /** 내보내기 제목/푸터 행. / Export title/footer row. */
@@ -564,27 +766,37 @@ export interface ExportHeaderRow {
564
766
  export interface GridOptions<T = any> {
565
767
  /** 컬럼 정의 배열(필수). / Column definitions (required). */
566
768
  columns: ColumnDef<T>[];
567
- /** 그리드 높이(px 숫자 또는 CSS 문자열). / Grid height (px number or CSS string). */
769
+ /**
770
+ * 그리드의 세로 크기. 숫자면 px, 문자열이면 CSS 값('60vh' 등)입니다. 가상 스크롤이 제대로 돌려면
771
+ * 확정된 높이가 필요하므로, 큰 데이터에서는 이 값(또는 조상 요소의 높이)을 꼭 주는 걸 권합니다.
772
+ * / The grid's vertical size — a number is px, a string is a CSS value ('60vh' …). Virtual scroll
773
+ * needs a definite height, so on large data set this (or an ancestor's height).
774
+ */
568
775
  height?: number | string;
569
- /** 그리드 폭(px 숫자 또는 CSS 문자열). / Grid width (px number or CSS string). */
776
+ /** 그리드의 가로 크기. 숫자면 px, 문자열이면 CSS 값. 생략 시 부모 폭을 채웁니다. / The grid's horizontal size — number = px, string = CSS. Unset fills the parent width. */
570
777
  width?: number | string;
571
- /** 행 높이(px). / Row height (px). */
778
+ /**
779
+ * 데이터 행 한 줄의 세로 픽셀 높이. 촘촘하게 많이 보이려면 줄이고, 터치·가독성 위주면 키웁니다.
780
+ * 가상 스크롤이 이 값으로 "화면에 몇 행이 들어갈지"를 계산합니다. 기본 32.
781
+ * / Height in px of one data row. Lower it to pack more rows in; raise it for touch/readability.
782
+ * Virtual scroll uses this to compute how many rows fit on screen. Default 32.
783
+ */
572
784
  rowHeight?: number;
573
- /** 헤더 행 높이(px). / Header row height (px). */
785
+ /** 머리글(헤더) 행의 높이(px). 여러 줄 헤더면 자동으로 늘어나므로 보통은 생략. / Header row height (px). Grows automatically for multi-line headers, so usually omitted. */
574
786
  headerHeight?: number;
575
- /** 푸터 행 높이(px). / Footer row height (px). */
787
+ /** 푸터(합계) 행의 높이(px). / Footer (totals) row height (px). */
576
788
  footerHeight?: number;
577
- /** 행 내용에 맞춰 행 높이 자동 확장(wrap 컬럼과 사용). / Auto-grow row height to content (use with wrap columns). */
789
+ /** 셀 내용이 길어 줄바꿈될 때 행 높이를 내용에 맞춰 자동으로 늘립니다. 컬럼의 wrap 과 함께 씁니다. / Auto-grow a row's height to fit wrapped content. Use together with a column's wrap. */
578
790
  autoHeight?: boolean;
579
- /** 컬럼 폭 합을 컨테이너 폭에 맞춤. / Stretch column widths to fill the container. */
791
+ /** 컬럼 폭의 합이 컨테이너를 꽉 채우도록 늘립니다. 오른쪽에 빈 공간을 남기고 싶지 않을 때. / Stretch column widths so their sum fills the container — when you don't want empty space on the right. */
580
792
  fillWidth?: boolean;
581
- /** width/flex 미지정 컬럼의 기본 폭(px). / Default width (px) for columns without width/flex. */
793
+ /** width 도 flex 도 안 준 컬럼에 적용할 기본 폭(px). / Fallback width (px) for columns given neither width nor flex. */
582
794
  defaultColumnWidth?: number;
583
795
  /**
584
796
  * 뷰포트 안전장치(옵트인, 기본 undefined = OFF = 기존 동작 완전 불변).
585
797
  * / Viewport safety net (opt-in; default undefined = OFF = behavior fully unchanged).
586
798
  * 호스트가 그리드 컨테이너 조상 체인에 확정 높이(definite height)를 주지 않으면
587
- * 내부 스페이서(totalRows×rowHeight)가 컨테이너를 전체 콘텐츠 크기로 부풀리고,
799
+ * 내부 스페이서(totalRows×rowHeight)가 컨테이너를 전체 콘텐츠 크기로 늘리고,
588
800
  * ResizeObserver 되먹임으로 windowing 이 무력화되어 전 행이 DOM 렌더되는 폭주가 발생한다
589
801
  * (대량 데이터일수록 재앙적). 이 값을 지정하면, 컨테이너가 전 콘텐츠를 다 담는 "언바운드"
590
802
  * 상태로 감지될 때에 한해 윈도잉 뷰포트 높이를 이 값(px)으로 클램프해 폭주를 차단한다.
@@ -598,47 +810,51 @@ export interface GridOptions<T = any> {
598
810
  * this option is a safety net.
599
811
  */
600
812
  fallbackViewportHeight?: number;
601
- /** 전역 편집 허용(컬럼별 editable 과 AND). / Global edit switch (ANDed with per-column editable). */
813
+ /** 그리드 전체의 편집 스위치. 켜져 있고 컬럼의 editable 도 참일 때만 실제로 편집이 열립니다(둘 다 참 조건). / The grid-wide edit switch. Editing opens only when this AND a column's editable are true. */
602
814
  editable?: boolean;
603
- /** 편집 진입 방식. / How editing is entered. */
815
+ /** 편집을 어떻게 시작할지. 'click'=한 번 클릭, 'dblclick'=더블클릭, 'none'=마우스로는 진입 불가(API 로만). / How editing starts — 'click' single click, 'dblclick' double click, 'none' no mouse entry (API only). */
604
816
  editMode?: 'click' | 'dblclick' | 'none';
605
- /** (예약) 편집 히스토리. / (Reserved) edit history. */
817
+ /** (예약) 편집 실행취소 히스토리 — 아직 미구현. / (Reserved) undo history for edits — not implemented yet. */
606
818
  history?: boolean;
607
- /** (예약) 히스토리 크기. / (Reserved) history size. */
819
+ /** (예약) 히스토리에 담을 최대 단계 수 — 아직 미구현. / (Reserved) max steps kept in history — not implemented yet. */
608
820
  historySize?: number;
609
- /** 선택 모드('cells' = F1 범위 선택). / Selection mode ('cells' = F1 range selection). */
821
+ /** 사용자가 무엇을 선택할 수 있는지. 'cells' 로 하면 스프레드시트식 범위 선택이 됩니다. / What the user can select. 'cells' enables spreadsheet-style range selection. */
610
822
  selection?: SelectionMode;
611
- /** 클립보드 복사/붙여넣기 허용. / Enable clipboard copy/paste. */
823
+ /** Ctrl+C / Ctrl+V 로 셀 값을 복사·붙여넣기하게 할지. / Whether Ctrl+C / Ctrl+V copy-paste of cell values is enabled. */
612
824
  clipboard?: boolean;
613
- /** F1: 범위 선택 + 채우기 핸들(C5.1 단일 중첩 — 최상위 flat 키 금지). / F1: range selection + fill handle (C5.1 single nesting — no top-level flat keys). */
825
+ /** 범위 선택 + 채우기 핸들(엑셀식 드래그 채우기) 세부 설정. / Range selection + fill handle (Excel-style drag-fill) detailed options. */
614
826
  rangeSelection?: RangeSelectionOptions;
615
- /** F3: 셀 수식(C5.1 단일 중첩). / F3: cell formulas (C5.1 single nesting). */
827
+ /** 셀 수식('=A1+B2' 같은 식) 기능 세부 설정. / Cell-formula ('=A1+B2'-style) detailed options. */
616
828
  formula?: FormulaOptions;
617
- /** F2: 마스터/디테일(C5.1 단일 중첩). / F2: master/detail (C5.1 single nesting). */
829
+ /** 마스터/디테일(행을 펼쳐 상세 패널 표시) 세부 설정. / Master/detail (expand a row into a detail panel) detailed options. */
618
830
  masterDetail?: MasterDetailOptions<T>;
619
- /** F4: 그리드 데이터 통합 차트(C5.1 단일 중첩). 타입은 chart/types 순환-안전 type-only import. / F4: grid-data integrated chart (C5.1 single nesting). Type is a cycle-safe type-only import from chart/types. */
831
+ /** 그리드 데이터를 그대로 쓰는 통합 차트 세부 설정. / Detailed options for the chart integrated on the grid's own data. */
620
832
  chart?: import('./chart/types.js').ChartGlobalOptions;
621
- /** DD-05: 조건부서식(CF) 규칙(opt-in, 기본 undefined=byte-identical). 지정 시 _mount 가 setConditionalFormat 로 배선(동적 import). 타입은 cf 순환-안전 type-only import. / DD-05: conditional-format rules (opt-in; default undefined = byte-identical). Type is a cycle-safe type-only import from cf. */
833
+ /**
834
+ * 조건부 서식 규칙 목록(값에 따라 셀을 데이터바·색조·아이콘으로 강조). 지정하지 않으면 아무 것도 바뀌지 않습니다.
835
+ * / Conditional-format rules — highlight cells by value with data-bars, color scales, or icon sets.
836
+ * Unset changes nothing.
837
+ */
622
838
  conditionalFormat?: import('./cf/CFRule.js').CFRule[];
623
- /** 전역 정렬 허용. / Global sort switch. */
839
+ /** 머리글 클릭 정렬을 그리드 전체에서 켤지. 컬럼별 sortable 로 예외를 둘 수 있습니다. / Turn header-click sorting on grid-wide. Per-column sortable can override. */
624
840
  sortable?: boolean;
625
- /** Shift+클릭 멀티정렬 허용. / Allow Shift+click multi-sort. */
841
+ /** Shift+클릭으로 여러 컬럼을 겹쳐 정렬(2차·3차 기준)하게 할지. / Whether Shift+click stacks multiple sort keys (secondary, tertiary …). */
626
842
  multiSort?: boolean;
627
- /** 전역 필터 허용. / Global filter switch. */
843
+ /** 필터 기능을 그리드 전체에서 켤지. 컬럼별 filterable 로 예외를 둘 수 있습니다. / Turn filtering on grid-wide. Per-column filterable can override. */
628
844
  filterable?: boolean;
629
- /** 초기 정렬 상태. / Initial sort state. */
845
+ /** 처음 로드될 때 미리 적용해 둘 정렬 상태. / The sort state to apply up front on first load. */
630
846
  defaultSort?: SortItem[];
631
- /** 왼쪽 고정 컬럼 수. / Number of left-frozen columns. */
847
+ /** 왼쪽부터 몇 개 컬럼을 가로 스크롤과 무관하게 고정할지. / How many leftmost columns stay pinned while scrolling horizontally. */
632
848
  frozenColumns?: number;
633
- /** (예약) 고정 행 수 — 미구현. / (Reserved) frozen row count — not implemented. */
849
+ /** (예약) 위쪽 고정 행 수 — 아직 미구현. / (Reserved) number of top-frozen rows — not implemented yet. */
634
850
  frozenRows?: number;
635
- /** 행 번호 컬럼 표시. / Show the row-number column. */
851
+ /** 맨 왼쪽에 1,2,3… 행 번호 컬럼을 붙일지. / Whether to add a leftmost 1,2,3… row-number column. */
636
852
  rowNumber?: boolean;
637
- /** 행 상태(추가/수정) 컬럼 표시. / Show the row-state (added/edited) column. */
853
+ /** 각 행이 추가/수정/삭제 중 어떤 상태인지 표시하는 컬럼을 붙일지(편집 추적용). / Whether to add a column showing each row's added/edited/removed state (for change tracking). */
638
854
  stateColumn?: boolean;
639
- /** 체크박스 컬럼 표시. / Show the checkbox column. */
855
+ /** 행 선택용 체크박스 컬럼을 붙일지. / Whether to add a checkbox column for selecting rows. */
640
856
  checkColumn?: boolean;
641
- /** 행 드래그 이동 허용. / Enable row drag & drop. */
857
+ /** 행을 드래그해 순서를 바꾸게 할지. / Whether rows can be dragged to reorder. */
642
858
  draggable?: boolean;
643
859
  /** 그리드↔그리드 행 드래그 이동 허용 (draggable:true 와 함께 사용, 양쪽 그리드 모두 true 여야 이동) / Enable grid-to-grid row drag (use with draggable:true; both grids must be true) */
644
860
  crossGrid?: boolean;
@@ -651,27 +867,32 @@ export interface GridOptions<T = any> {
651
867
  crossGridMapping?: 'auto' | 'interactive' | ((srcRow: T) => Partial<T>);
652
868
  /** 셀 병합 기능 사용. / Enable cell merging. */
653
869
  mergeCells?: boolean;
654
- /** 초기 그룹핑 필드. / Initial grouping fields. */
870
+ /** 처음부터 이 필드들로 행을 묶어 보여 줄지. 여러 개면 다단계 그룹이 됩니다(예: 지역 → 부서). / Which fields to group rows by from the start. Several means nested groups (e.g. region → dept). */
655
871
  groupBy?: string[];
656
- /** 그룹 소계/합계 옵션. / Group summary options. */
872
+ /** 각 그룹에 소계/합계 요약 행을 붙이는 설정. / Options for attaching subtotal/summary rows to each group. */
657
873
  summary?: SummaryOptions;
658
- /** 트리 구성 방식('auto' = children 중첩, 'flat' = id/parentId 평면). / Tree build mode ('auto' = nested children, 'flat' = id/parentId pairs). */
874
+ /**
875
+ * 트리(계층) 데이터를 어떤 모양으로 받을지. 'auto'=각 행이 children 배열로 자식을 품은 중첩 구조,
876
+ * 'flat'=모든 행이 한 줄이고 id/부모id 로 관계를 표현하는 평면 구조.
877
+ * / How hierarchical data is shaped. 'auto' = each row nests its children in a children array;
878
+ * 'flat' = every row is a flat entry linked by id / parent-id.
879
+ */
659
880
  treeMode?: 'auto' | 'flat';
660
- /** flat 트리의 id 필드명. / id field name for flat tree mode. */
881
+ /** flat 트리에서 각 행의 고유 id 가 담긴 필드 이름. / In flat tree mode, the field holding each row's unique id. */
661
882
  treeId?: string;
662
- /** flat 트리의 부모 id 필드명. / parent-id field name for flat tree mode. */
883
+ /** flat 트리에서 부모 행의 id 가 담긴 필드 이름. / In flat tree mode, the field holding the parent row's id. */
663
884
  treeParentId?: string;
664
- /** 로드 시 전체 펼침. / Expand all nodes on load. */
885
+ /** 로드하자마자 모든 노드를 펼쳐 둘지. / Whether to expand every node right after loading. */
665
886
  expandOnLoad?: boolean;
666
- /** 페이징 바 사용. / Enable the pagination bar. */
887
+ /** 아래쪽 페이지 이동 바를 띄울지. / Whether to show the pagination bar at the bottom. */
667
888
  pagination?: boolean;
668
- /** 페이지당 행 수. / Rows per page. */
889
+ /** 한 페이지에 몇 행을 보일지. / How many rows show per page. */
669
890
  pageSize?: number;
670
- /** 푸터 셀 정의 배열. / Footer cell definitions. */
891
+ /** 아래(또는 위) 고정 푸터에 넣을 셀 정의들(합계 줄 등). / Cell definitions for the pinned footer (e.g. a totals row). */
671
892
  footer?: FooterDef[];
672
- /** 푸터 위치. / Footer position. */
893
+ /** 푸터를 아래('bottom')에 둘지 위('top')에 둘지. / Put the footer at the bottom ('bottom') or top ('top'). */
673
894
  footerPosition?: 'top' | 'bottom';
674
- /** 툴팁: true 면 모든 셀에 native title(값) 자동 노출. 컬럼별 col.tooltip 이 우선. / true auto-exposes native title (cell value) on every cell; per-column col.tooltip wins. */
895
+ /** true 면 모든 셀에 마우스를 올렸을 때 그 값이 브라우저 기본 툴팁으로 뜹니다. 컬럼의 tooltip 설정이 있으면 그쪽이 우선. / true shows every cell's value as a native browser tooltip on hover; a column's own tooltip wins. */
675
896
  tooltips?: boolean;
676
897
  /** 그리드 컨테이너 aria-label. / aria-label of the grid container. */
677
898
  ariaLabel?: string;
@@ -679,9 +900,9 @@ export interface GridOptions<T = any> {
679
900
  theme?: string;
680
901
  /** 스킨 (FORM 축, R12b) — data-og-skin. 미지정 시 'default'(오늘과 byte-identical). / Skin (FORM axis, R12b) — data-og-skin. Default 'default' (byte-identical to stock look). */
681
902
  skin?: string;
682
- /** DD-11: 밀도 (DENSITY 축) — data-og-density. 미지정 시 미적용(byte-identical). / Density (DENSITY axis, DD-11) — data-og-density. Unset = not applied (byte-identical). */
903
+ /** 행 간격(밀도) 이름. 촘촘·보통·여유처럼 행 높이와 여백을 통째로 바꿉니다. 지정하지 않으면 아무 것도 바뀌지 않습니다. / The row-spacing (density) name — compact/normal/roomy row heights and paddings. Unset changes nothing. */
683
904
  density?: string;
684
- /** DD-11: 질감 (TEXTURE 축) — data-og-texture. 미지정 시 미적용(byte-identical). / Texture (TEXTURE axis, DD-11) — data-og-texture. Unset = not applied (byte-identical). */
905
+ /** 배경 질감(패턴) 이름. 셀 배경에 무늬만 입힙니다. 지정하지 않으면 아무 것도 바뀌지 않습니다. / The background texture (pattern) name — paints a pattern on cell backgrounds. Unset changes nothing. */
685
906
  texture?: string;
686
907
  /** 컨테이너에 주입할 CSS 변수 맵. / CSS custom properties injected on the container. */
687
908
  cssVars?: Record<string, string>;
@@ -696,15 +917,20 @@ export interface GridOptions<T = any> {
696
917
  * / Per-instance partial message override (2-level deep-merge over the catalog). Per-label option > messages > catalog.
697
918
  */
698
919
  messages?: PartialLocaleMessages;
699
- /** F3: 우클릭 컨텍스트 메뉴(false=끔, 배열=커스텀 항목). / F3: right-click context menu (false = off, array = custom items). */
920
+ /** 우클릭 컨텍스트 메뉴. true=기본 메뉴, false=끔, 배열=직접 정한 항목들. / Right-click context menu — true = default menu, false = off, array = your own items. */
700
921
  contextMenu?: boolean | ContextMenuItem[];
701
- /** F2: 워크시트(다중시트). / F2: worksheets (multi-sheet tabs). */
922
+ /** 엑셀처럼 하단 탭으로 여러 시트를 전환하는 워크시트 정의들. / Worksheet definitions — Excel-like bottom tabs switching between multiple sheets. */
702
923
  worksheets?: WorksheetDef[];
703
- /** F4: 전체 기본 소수점 정밀도 (기본 10) / F4: global default decimal precision (default 10) */
924
+ /** 수식·집계 계산에 쓸 기본 소수점 정밀도. 기본 10. / Default decimal precision for formulas/aggregation. Default 10. */
704
925
  calcPrecision?: number;
705
- /** 컬럼 드래그 리오더 허용. / Enable column drag reorder. */
926
+ /** 머리글을 드래그해 컬럼 순서를 바꾸게 할지. / Whether headers can be dragged to reorder columns. */
706
927
  columnReorder?: boolean;
707
- /** override 커널: 레이어 예외를 기본 전파(strict). false → fallback 옵트인 동작 허용 / Override kernel: propagate layer exceptions by default (strict). false allows the fallback opt-in behavior. */
928
+ /**
929
+ * override 로 감싼 함수에서 예외가 나면 어떻게 할지. 기본(true, strict)은 예외를 그대로 전파합니다.
930
+ * false 로 하면 경고 후 원본 함수를 실행하는 완화(fallback) 동작을 허용합니다.
931
+ * / What happens when an overridden layer throws. Default (true, strict) propagates the error;
932
+ * false permits the softer fallback that warns then runs the original.
933
+ */
708
934
  overrideStrict?: boolean;
709
935
  /** 첫 렌더 완료 콜백. / Fired after the first render. */
710
936
  onReady?: (grid: OpenGridInstance<T>) => void;
@@ -715,14 +941,15 @@ export interface GridOptions<T = any> {
715
941
  onEditBefore?: (e: EditEvent<T>) => boolean;
716
942
  onRowClick?: (e: RowEvent<T>) => void;
717
943
  onSelectionChange?: (e: SelectionEvent<T>) => void;
718
- /** F1: 범위 rects 변경 시(C4, F4 라이브 소비) / F1: fired when range rects change (C4; consumed live by F4) */
944
+ /** 선택된 셀 범위가 바뀔 때마다 호출(차트가 이걸 실시간으로 구독하기도 함). / Fired whenever the selected cell range changes (the chart can subscribe to it live). */
719
945
  onRangeChange?: (e: RangeChangeEvent) => void;
720
- /** F1: 채우기 커밋 결과(§6.3) / F1: fill commit result (§6.3) */
946
+ /** 채우기 핸들로 값 채우기가 확정된 뒤, 무엇이 어떻게 채워졌는지 결과를 전달. / After a fill-handle fill commits, delivers what was filled and how. */
721
947
  onRangeFill?: (e: RangeFillEvent) => void;
722
- /** F1: 범위 복사 시(§6.3) / F1: fired on range copy (§6.3) */
948
+ /** 선택 범위를 복사(Ctrl+C)했을 때 호출. / Fired when the selected range is copied (Ctrl+C). */
723
949
  onRangeCopy?: (e: RangeCopyEvent) => void;
724
- /** F2: 행 상세 패널 펼침/접힘 시(C5.1 on* 버킷). / F2: fired when a detail panel expands/collapses (C5.1 on* bucket). */
950
+ /** 행 상세 패널이 펼쳐질 때 호출. / Fired when a row's detail panel expands. */
725
951
  onRowExpand?: (e: RowExpandEvent<T>) => void;
952
+ /** 행 상세 패널이 접힐 때 호출. / Fired when a row's detail panel collapses. */
726
953
  onRowCollapse?: (e: RowExpandEvent<T>) => void;
727
954
  onSortChange?: (e: SortEvent) => void;
728
955
  onFilterChange?: (e: FilterEvent) => void;
@@ -773,13 +1000,21 @@ export interface OverrideCallOptions {
773
1000
  /** 등록 가능한 알고리즘 슬롯 이름. / Registerable algorithm slot names. */
774
1001
  export type StrategySlot = 'sortComparator' | 'filterPredicate' | 'displayFormatter' | 'cellSerializer' | 'groupKeyFn' | 'summaryOp' | 'cellClassResolver' | 'ariaLabelResolver' | 'skinResolver';
775
1002
  /**
776
- * SKIN 토큰 이름 집합 — **형태(FORM)만** 소유(색 0). COLOR 토큰과 disjoint name set 이라
777
- * 색⊥형태 직교성이 이름 충돌 부재로 물리적으로 보장된다(item3 §1.1~1.2, HANMS §4).
778
- * / SKIN token name set — owns **FORM only** (zero colors). Being name-disjoint from COLOR
779
- * tokens physically guarantees color⊥form orthogonality.
1003
+ * 스킨이 조절할 수 있는 CSS 변수 이름들의 목록입니다. 여기 담긴 것은 모두 "형태"에 관한 값(모서리 둥글기,
1004
+ * 테두리 두께, 그림자, 여백, 질감 등)뿐이고 색은 하나도 없습니다. 색은 별도의 테마(COLOR) 축이 맡습니다.
1005
+ * 이렇게 이름 자체를 색과 겹치지 않게 나눠 두어, 스킨을 바꿔도 색은 영향받지 않도록 보장합니다.
1006
+ * / The set of CSS-variable names a skin may adjust. Every one of these is about *form* (corner
1007
+ * radius, border width, elevation, spacing, texture …) and none are colors — color is owned by the
1008
+ * separate theme (COLOR) axis. Keeping the names disjoint guarantees a skin change never touches color.
780
1009
  */
781
1010
  export type SkinTokenName = '--og-radius-none' | '--og-radius-sm' | '--og-radius-md' | '--og-radius-lg' | '--og-radius-pill' | '--og-radius-container' | '--og-radius-control' | '--og-radius-widget' | '--og-container-radius' | '--og-border-width' | '--og-border-width-strong' | '--og-border-style' | '--og-divider-style' | '--og-divider-repeat' | '--og-elevation-sm' | '--og-elevation-md' | '--og-elevation-lg' | '--og-elevation-alpha-sm' | '--og-elevation-alpha-md' | '--og-elevation-alpha-lg' | '--og-elevation-inset' | '--og-cell-padding-x' | '--og-cell-padding-y' | '--og-density-row-height' | '--og-density-header-height' | '--og-density-footer-height' | '--og-scrollbar-size' | '--og-texture-bg' | '--og-texture-size' | '--og-texture-opacity' | '--og-focus-width' | '--og-focus-style' | '--og-focus-offset' | '--og-focus-radius' | '--og-icon-size' | '--og-icon-fill' | '--og-icon-stroke-width' | '--og-icon-corner' | '--og-transition-fast' | '--og-transition-base' | '--og-row-accent-width';
782
- /** FORM-only 스킨 델타. 값에 색 리터럴이 있으면 SkinRegistry 가 런타임 거부(Rule 2, 직교성). / FORM-only skin delta. Color literals in values are rejected at runtime by SkinRegistry (Rule 2, orthogonality). */
1011
+ /**
1012
+ * 스킨 하나가 바꾸는 "형태 변수 → 값" 묶음입니다(바꾸고 싶은 것만 골라 담는 부분 지정). 형태 전용이라,
1013
+ * 값에 색(예: '#fff')을 넣으면 등록 시점에 거부됩니다 — 색은 테마 축의 몫이기 때문입니다.
1014
+ * / A skin's bundle of "form variable → value" overrides (partial — include only what you change).
1015
+ * It is form-only: putting a color literal (e.g. '#fff') in a value is rejected at registration,
1016
+ * because color belongs to the theme axis.
1017
+ */
783
1018
  export type SkinTokenDelta = Partial<Record<SkinTokenName, string>>;
784
1019
  /** 단일키 정렬 비교자. dir 부호는 호출자(DataLayer)가 적용 — 슬롯은 비교만 반환. / Single-key sort comparator. The dir sign is applied by the caller (DataLayer) — the slot only compares. */
785
1020
  export type SortComparatorFn = (a: any, b: any, field: string, dir: 'asc' | 'desc') => number;
@@ -793,15 +1028,15 @@ export type CellSerializerFn = (value: any, col: any, row: any) => any;
793
1028
  export type GroupKeyFn = (row: any, remainingFields: string[]) => any;
794
1029
  /** 집계 연산. null 반환 시 기본 SUM/AVG/COUNT/MAX/MIN 분기로 폴백. / Aggregate operator. Returning null falls back to the built-in SUM/AVG/COUNT/MAX/MIN branch. */
795
1030
  export type SummaryOpFn = (op: string, nums: any[], field: string) => number | null;
796
- /** R11(§4.2): 셀 클래스 렌더훅 리졸버. 렌더층이 셀 element 에 추가할 className(null=미참여). / R11 (§4.2): cell-class render-hook resolver. className the render layer adds to the cell element (null = not participating). */
1031
+ /** 셀마다 CSS 클래스 이름을 붙여 주는 함수 슬롯. 값·행에 따라 셀에 추가할 className 을 돌려줍니다(null 이면 아무 것도 안 붙임). / A slot that assigns a CSS class per cell — return the className to add based on value/row (null adds nothing). */
797
1032
  export type CellClassResolverFn = (value: any, field: string, row: any) => string | null;
798
- /** R11(§4.2): 셀 aria-label 렌더훅 리졸버. 렌더층이 셀 aria-label 을 대체(null=기본 유지). / R11 (§4.2): cell aria-label render-hook resolver. Replaces the cell aria-label (null = keep default). */
1033
+ /** 셀의 스크린리더용 라벨(aria-label)을 바꿔 주는 함수 슬롯. 대체 라벨을 돌려줍니다(null 이면 기본값 유지). / A slot that overrides a cell's screen-reader label (aria-label) — return a replacement (null keeps the default). */
799
1034
  export type AriaLabelResolverFn = (value: any, field: string, row: any) => string | null;
800
1035
  /**
801
- * F1 채우기 시리즈 커스텀 리졸버 슬롯(C5.3, 예약). 사용자가 날짜/커스텀 시리즈를 주입할 수 있다.
802
- * ⚠️ 슬롯 등록 경로만 확보되어 있으며, RangeSelectionManager/FillEngine 소비 배선은 F1-b(Full) 대상.
803
- * / F1 custom fill-series resolver slot (C5.3, reserved). Lets users inject date/custom series.
804
- * ⚠️ Only the registration path exists; consumption wiring is scheduled for F1-b (Full).
1036
+ * 채우기 핸들의 "이어 채우기" 규칙을 직접 정의하는 함수 슬롯입니다(예: 날짜·요일·사용자 정의 수열).
1037
+ * ⚠️ 지금은 등록 통로만 열려 있고 실제 채우기에 연결되는 배선은 향후 버전에서 제공됩니다.
1038
+ * / A slot to define your own fill-series rule for the fill handle (dates, weekdays, custom sequences).
1039
+ * ⚠️ Only the registration path exists today; the wiring that actually consumes it ships in a later version.
805
1040
  */
806
1041
  export type FillSeriesResolverFn = (sourceLine: any[], k: number, axisSign: 1 | -1) => any;
807
1042
  /** 슬롯명 → 시그니처 매핑. / Slot name → signature map. */
@@ -818,57 +1053,65 @@ export interface StrategyMap {
818
1053
  skinResolver: SkinResolverFn;
819
1054
  }
820
1055
  /**
821
- * R12b(item3 §6.1): 스킨 FORM 해석 인터셉트 슬롯. AppearanceResolver 가 fallback 과 함께 읽어(제로코스트)
822
- * 오버라이드가 form 토큰 델타를 통째로 가로챌 수 있다. 미설정 시 내장 스킨 카탈로그가 그대로 적용.
823
- * / R12b (item3 §6.1): skin FORM resolution intercept slot. AppearanceResolver reads it with a
824
- * fallback (zero-cost) so an override can hijack the whole form-token delta. When unset, the
825
- * built-in skin catalog applies as-is.
1056
+ * 스킨 이름을 받아 그 스킨의 형태 변수 묶음을 직접 만들어 돌려주는 함수 슬롯입니다. 내장 스킨 대신 나만의
1057
+ * 스킨 해석 규칙을 통째로 끼워 넣을 때 씁니다(null 을 돌려주면 내장 스킨 카탈로그를 그대로 사용).
1058
+ * / A slot that takes a skin name and returns that skin's form-variable bundle — plug in your own
1059
+ * skin-resolution rule in place of the built-ins (return null to fall back to the built-in catalog).
826
1060
  */
827
1061
  export type SkinResolverFn = (skinId: string) => SkinTokenDelta | null;
828
1062
  /**
829
- * R11(§4.3, T-ζ): SemVer 보증되는 **타입드 override 카탈로그**(좁은 "지원됨" 문).
830
- * `override("anyMethod", fn)` 문자열 탈출구(UC-11, best-effort)는 그대로 열려 있고 —
831
- * 이 인터페이스는 축복된(blessed) 확장점 이름을 IDE 발견가능하게 좁게 표시할 뿐, 넓은 문을 닫지 않는다.
832
- * 각 항목은 소비 테스트를 동반한다(유령 확장점 금지, DeMarco M9b).
833
- * / R11 (§4.3, T-ζ): SemVer-guaranteed **typed override catalog** (the narrow "supported"
834
- * statement). The `override("anyMethod", fn)` string escape hatch (UC-11, best-effort) stays
835
- * open — this interface only surfaces blessed extension-point names for IDE discovery.
1063
+ * override 로 감싸는 것이 **공식적으로 보장되는** 확장점 이름들의 목록입니다. 이 이름들은 버전이 올라가도
1064
+ * 유지되며 IDE 자동완성에 뜹니다. 목록에 없는 임의 메서드 이름도 override("이름", fn) 문자열 방식으로 감쌀 수
1065
+ * 있지만(최선 노력), 그건 보장 밖입니다.
1066
+ * / The list of extension points whose override is **officially guaranteed** — these names survive
1067
+ * version bumps and show up in IDE autocomplete. Any other method name can still be wrapped via the
1068
+ * string form override("name", fn) on a best-effort basis, but without that guarantee.
836
1069
  */
837
1070
  export interface OverridePoints<T = any> {
838
- /** 셀 표시 텍스트 해석(렌더훅 displayText 의 근원). / Cell display-text resolution (source of the displayText render hook). */
1071
+ /** 셀에 실제로 보이는 텍스트를 계산하는 지점. / Where a cell's visible display text is computed. */
839
1072
  getDisplayValue(rowIndex: number, field: string): string;
840
- /** 원시 셀 값 접근. / Raw cell value access. */
1073
+ /** 셀의 원시 값을 읽는 지점. / Where a cell's raw value is read. */
841
1074
  readCell(rowIndex: number, field: string): any;
842
1075
  }
843
- /** 호출가능 + .strategy 멤버를 가진 하이브리드 override API. / Hybrid override API: callable plus a .strategy member. */
1076
+ /**
1077
+ * grid.override 의 두 얼굴입니다 — 그 자체를 함수처럼 불러 메서드를 감쌀 수도 있고(override(...)),
1078
+ * .strategy(...) 로 정렬·포맷 같은 알고리즘 슬롯을 갈아 끼울 수도 있습니다. 모든 호출은 체이닝을 위해
1079
+ * 그리드 인스턴스를 다시 돌려줍니다.
1080
+ * / The two faces of grid.override — call it like a function to wrap a method (override(...)), or use
1081
+ * .strategy(...) to swap an algorithm slot like sorting/formatting. Every call returns the grid
1082
+ * instance for chaining.
1083
+ */
844
1084
  export interface OverrideApi<T = any> {
845
- /** R11(§4.3): 타입드 오버로드 — 축복된 확장점 이름(IDE 발견). SemVer 보증 카탈로그. / R11 (§4.3): typed overload — blessed extension-point names (IDE discovery). SemVer-guaranteed catalog. */
1085
+ /** 보장된 확장점 이름을 감싸는 타입드 오버로드(IDE 자동완성). / Typed overload for the guaranteed extension-point names (IDE autocomplete). */
846
1086
  <K extends keyof OverridePoints<T>>(name: K, fn: OverrideLayerFn, opts?: OverrideCallOptions): OpenGridInstance<T>;
847
- /** 메서드 본문 무수정 런타임 래핑(C1-clean, 탈출구 UC-11). 체이닝 위해 grid 인스턴스 반환. / Runtime wrapping without touching method bodies (C1-clean, escape hatch UC-11). Returns the grid instance for chaining. */
1087
+ /** 임의 메서드를 본문 수정 없이 런타임에 감쌉니다(문자열 이름 방식). 체이닝을 위해 그리드를 반환. / Wrap any method at runtime without touching its body (string-name form). Returns the grid for chaining. */
848
1088
  (name: string, fn: OverrideLayerFn, opts?: OverrideCallOptions): OpenGridInstance<T>;
849
- /** 알고리즘 슬롯 등록(Phase 2 매니저 훅포인트). 체이닝 위해 grid 인스턴스 반환. / Register an algorithm slot (Phase 2 manager hook point). Returns the grid instance for chaining. */
1089
+ /** 알고리즘 슬롯 하나를 내 함수로 등록합니다. 체이닝을 위해 그리드를 반환. / Register one algorithm slot with your function. Returns the grid for chaining. */
850
1090
  strategy<K extends StrategySlot>(slot: K, fn: StrategyMap[K]): OpenGridInstance<T>;
851
1091
  strategy(slot: string, fn: Function): OpenGridInstance<T>;
852
1092
  }
853
1093
  /**
854
- * 그리드 공개 인스턴스 계약(OpenGrid 가 구현). 세부 문서는 OpenGrid 클래스 참조.
855
- * / Public grid instance contract (implemented by OpenGrid). See the OpenGrid class for
856
- * per-method documentation.
1094
+ * `new OpenGrid(...)` 로 만든 그리드가 밖에 내어 주는 조작 창구(메서드 모음)입니다. 데이터 넣기·읽기,
1095
+ * 행·컬럼 편집, 정렬·필터, 선택, 내보내기, 테마 전환 등 그리드에게 시킬 수 있는 모든 일이 여기 모여 있습니다.
1096
+ * 각 메서드의 자세한 설명은 이 계약을 구현하는 OpenGrid 클래스 쪽에 있습니다.
1097
+ * / The set of methods a grid built with `new OpenGrid(...)` exposes — everything you can ask the
1098
+ * grid to do: load/read data, edit rows & columns, sort/filter, select, export, switch themes, and
1099
+ * more. Per-method detail lives on the OpenGrid class that implements this contract.
857
1100
  *
858
1101
  * @typeParam T - 행 데이터 타입 / Row data type
859
1102
  */
860
1103
  export interface OpenGridInstance<T = any> {
861
- /** 공개 메서드를 런타임 래핑하거나(.override) 알고리즘 슬롯을 등록(.strategy). */
1104
+ /** 공개 메서드를 런타임에 감싸 동작을 바꾸거나(.override), 정렬·포맷 같은 알고리즘 슬롯을 갈아 끼웁니다(.strategy). / Wrap a public method at runtime to change its behavior (.override), or swap an algorithm slot like sorting/formatting (.strategy). */
862
1105
  override: OverrideApi<T>;
863
- /** 단일 메서드 원본 복구. */
1106
+ /** 이름을 지정한 메서드 하나를 원래 동작으로 되돌립니다. / Restore one named method to its original behavior. */
864
1107
  restore(name: string): OpenGridInstance<T>;
865
- /** 전체 override + strategy 복구(destroy 시 자동). */
1108
+ /** 걸어 둔 모든 override 와 strategy 를 한 번에 되돌립니다(그리드 파기 시 자동 호출). / Undo all overrides and strategies at once (called automatically on destroy). */
866
1109
  restoreAll(): OpenGridInstance<T>;
867
- /** 해당 메서드가 override 되어 있는지. */
1110
+ /** 그 메서드가 지금 override 로 감싸져 있는지 확인합니다. / Check whether that method is currently overridden. */
868
1111
  hasOverride(name: string): boolean;
869
- /** override 등록된 메서드 이름 목록. */
1112
+ /** override 로 감싼 메서드 이름들의 목록을 돌려줍니다. / Return the list of overridden method names. */
870
1113
  getOverrideNames(): string[];
871
- /** strategy 슬롯 조회(미등록 시 fallback 반환). 매니저 read API. */
1114
+ /** 등록된 알고리즘 슬롯 함수를 가져옵니다(없으면 넘긴 fallback 을 그대로 반환). / Fetch a registered algorithm-slot function (returns the given fallback if none). */
872
1115
  getStrategy<F extends Function>(slot: string, fallback: F): F;
873
1116
  setData(data: T[]): void;
874
1117
  getData(): T[];
@@ -877,10 +1120,11 @@ export interface OpenGridInstance<T = any> {
877
1120
  prefixData(data: T[]): void;
878
1121
  clearData(): void;
879
1122
  /**
880
- * DD-05: 조건부서식(CF) 규칙 설정 — 데이터바·히트맵·아이콘셋을 렌더 경로에 배선(opt-in, 동적 import).
881
- * 규칙이 걸린 컬럼 통계를 캐시 계산 후 재렌더한다. 빈 배열이면 CF 해제(잔재 제거).
882
- * / DD-05: set conditional-format rules — wires data-bars/heatmaps/icon-sets into the render path
883
- * (opt-in, dynamic import). Caches rule-bearing column stats, then re-renders. Empty array clears CF.
1123
+ * 조건부 서식 규칙을 지정합니다 — 값에 따라 셀에 데이터바·색조(히트맵)·아이콘셋을 입혀 강조합니다.
1124
+ * 규칙이 걸린 컬럼의 통계(최소·최대 등)를 미리 계산해 두고 다시 그립니다. 빈 배열을 주면 조건부 서식을 모두 해제합니다.
1125
+ * / Set conditional-format rules — highlight cells by value with data-bars, color scales (heatmaps),
1126
+ * or icon sets. It precomputes the rule-bearing columns' stats (min/max …) and re-renders. Pass an
1127
+ * empty array to clear all conditional formatting.
884
1128
  */
885
1129
  setConditionalFormat(rules: import('./cf/CFRule.js').CFRule[]): Promise<void>;
886
1130
  insertRow(item: Partial<T>, position?: Position): void;
@@ -893,15 +1137,17 @@ export interface OpenGridInstance<T = any> {
893
1137
  getDisplayValue(rowIndex: number, field: string): string;
894
1138
  writeCell(rowIndex: number, field: string, value: any): void;
895
1139
  getRowAt(rowIndex: number): T;
896
- /** flat/visual index ↔ data 리졸버. F1/F3/F4 는 이 모델을 경유해 대상을 해소한다. */
1140
+ /** 화면에 보이는 행 순서와 실제 데이터를 이어 주는 내부 모델을 돌려줍니다(고급 배선용). / Return the internal model mapping on-screen row order to actual data (for advanced wiring). */
897
1141
  getFlatRowModel(): import('./FlatRowModel.js').FlatRowModel;
898
- /** 배치 쓰기 시작 — 이후 writeCell 들의 render/dataChange 를 지연·coalesce(reentrant). */
1142
+ /** 여러 셀을 한꺼번에 쓸 때, 이 호출 이후의 writeCell 들이 즉시 다시 그리지 않도록 렌더를 잠시 미룹니다. / Start a batch — subsequent writeCell calls defer their render/change events instead of firing each time. */
899
1143
  beginBatch(): void;
900
- /** 배치 종료 — 배치 중 쓰기가 있었으면 1회 render + 1회 coalesced dataChange. */
1144
+ /** 배치를 끝내고, 그 사이 변경이 있었으면 단 한 번만 다시 그리고 변경 이벤트도 한 번만 냅니다. / End the batch — if anything changed, render once and emit one coalesced change event. */
901
1145
  endBatch(): void;
902
1146
  /**
903
- * beginBatch+루프+endBatch 래퍼. rowIndex 는 flat index — kind!=='data' 대상(group/tree/
904
- * detail 의사행)은 쓰기 전에 skip 한다(C0.3 쓰기 안전). 반환값 = 건너뛴 셀 수.
1147
+ * 여러 셀 쓰기를 한 번에 처리하는 간편 래퍼(beginBatch → 반복 쓰기 → endBatch). rowIndex 는 화면
1148
+ * 표시 순서이며, 그룹·트리·상세 같은 실제 데이터가 아닌 가상 행은 안전하게 건너뜁니다. 반환값은 건너뛴 셀 수입니다.
1149
+ * / A convenience wrapper that writes many cells at once (beginBatch → loop → endBatch). rowIndex is
1150
+ * screen-order; non-data pseudo-rows (group/tree/detail) are safely skipped. Returns how many were skipped.
905
1151
  */
906
1152
  writeCells(patches: Array<{
907
1153
  rowIndex: number;
@@ -949,63 +1195,75 @@ export interface OpenGridInstance<T = any> {
949
1195
  getActiveRow(): number;
950
1196
  activate(index: number): void;
951
1197
  deselect(): void;
952
- /** 정규화 rects(없으면 []). MVP 는 길이 ≤1. */
1198
+ /** 현재 선택된 셀 범위들(없으면 빈 배열). 지금은 한 번에 하나까지 담깁니다. / Currently selected cell ranges (empty if none). At most one for now. */
953
1199
  getRangeSelection(): CellRange[];
954
- /** = getRangeSelection()[0] ?? null(C4, F4 소비). */
1200
+ /** 지금 활성인 범위 하나(없으면 null). 차트가 이 값을 읽어 씁니다. / The single active range (null if none). The chart reads this. */
955
1201
  getActiveRange(): CellRange | null;
1202
+ /** 셀 범위를 프로그램에서 직접 선택합니다. / Select a cell range programmatically. */
956
1203
  setRangeSelection(range: CellRange | CellRange[]): void;
1204
+ /** 현재 범위 선택을 모두 해제합니다. / Clear the current range selection. */
957
1205
  clearRangeSelection(): void;
958
- /** 현재 활성 범위의 값 2D 배열(FR-6, F4 필수 계약). */
1206
+ /** 현재 활성 범위 안 셀 값들을 행×열 2차원 배열로 돌려줍니다(차트가 소비). / Return the active range's cell values as a 2-D (rows×cols) array (consumed by the chart). */
959
1207
  getRangeValues(): any[][];
960
- /** 현재 활성 범위 숫자 셀의 OGDecimal 기반 통계(FR-6, F4 필수 계약). */
1208
+ /** 현재 활성 범위의 숫자 셀 통계(합·평균·최소·최대 등, 고정밀 계산). 숫자가 없으면 null. / High-precision stats (sum/avg/min/max …) over the active range's numeric cells; null if none. */
961
1209
  getRangeStats(): _RangeStats | null;
962
- /** source→target 채우기(배치 경유, C2). axis 는 두 rect 상대 위치로 추론. */
1210
+ /** 원본 범위의 값을 대상 범위로 채웁니다. 'copy'=그대로 복사, 'series'=규칙 감지해 이어 채우기. / Fill the target range from the source — 'copy' duplicates, 'series' detects a pattern and extends. */
963
1211
  fillRange(source: CellRange, target: CellRange, mode?: 'copy' | 'series'): void;
1212
+ /** 그리드 데이터로 차트를 만들어 인스턴스를 돌려줍니다. / Create a chart from grid data and return its instance. */
964
1213
  createChart(config: import('./chart/types.js').ChartConfig): import('./chart/types.js').ChartInstance;
1214
+ /** 이 그리드에 붙어 있는 차트 인스턴스들. / The chart instances attached to this grid. */
965
1215
  getCharts(): import('./chart/types.js').ChartInstance[];
1216
+ /** 이 그리드의 차트를 모두 정리(해제)합니다. / Dispose all charts on this grid. */
966
1217
  destroyCharts(): void;
967
- /** "=A1+B2" 형태. rowIndex 는 flat(C0), 내부 즉시 stable rowId 로 정규화. */
1218
+ /** 셀에 수식을 넣습니다(예: "=A1+B2"). rowIndex 는 화면 순서로 주면 내부에서 안정적 참조로 바꿉니다. / Set a cell's formula (e.g. "=A1+B2"). Pass rowIndex in screen order; it's normalized to a stable ref inside. */
968
1219
  setCellFormula(rowIndex: number, field: string, formula: string): void;
1220
+ /** 그 셀의 수식 원문(없으면 null). / The cell's formula text (null if none). */
969
1221
  getCellFormula(rowIndex: number, field: string): string | null;
1222
+ /** 그 셀에 수식이 들어 있는지. / Whether that cell holds a formula. */
970
1223
  hasCellFormula(rowIndex: number, field: string): boolean;
971
- /** 수식 제거(값은 유지). */
1224
+ /** 셀의 수식만 지웁니다(마지막 계산 값은 남습니다). / Remove the cell's formula (keeps the last computed value). */
972
1225
  clearCellFormula(rowIndex: number, field: string): void;
1226
+ /** 그 셀의 수식 오류 코드(오류가 없으면 null). / The cell's formula error code (null if none). */
973
1227
  getCellError(rowIndex: number, field: string): FormulaErrorCode | null;
974
- /** 디버깅용 — 이 셀을 참조하는(종속) 셀들. */
1228
+ /** 디버깅용 — 이 셀을 참조하는(이 셀이 바뀌면 다시 계산되는) 셀들. / Debug — cells that reference this one (recomputed when it changes). */
975
1229
  getDependents(rowIndex: number, field: string): Array<{
976
1230
  rowIndex: number;
977
1231
  field: string;
978
1232
  }>;
979
- /** 디버깅용 — 이 셀이 참조하는(선행) 셀들. */
1233
+ /** 디버깅용 — 이 셀의 수식이 참조하는(이 셀보다 먼저 계산돼야 하는) 셀들. / Debug — cells this one's formula references (computed before it). */
980
1234
  getPrecedents(rowIndex: number, field: string): Array<{
981
1235
  rowIndex: number;
982
1236
  field: string;
983
1237
  }>;
984
- /** 전체 수식 위상 재계산(setData/컬럼 변경 등). */
1238
+ /** 모든 수식을 처음부터 다시 계산합니다(데이터 교체·컬럼 변경 후 등). / Recompute every formula from scratch (after replacing data, changing columns, …). */
985
1239
  recalculate(): void;
986
- /** 단일 셀 + 종속 폐포만 재계산. */
1240
+ /** 이 셀과, 이 셀에 딸린(종속) 셀들만 다시 계산합니다. / Recompute only this cell and the cells depending on it. */
987
1241
  recalculateCell(rowIndex: number, field: string): void;
988
- /** C3(F1 fill 전용): srcRowId/srcField 수식의 상대축만 dRow/dCol 오프셋한 새 수식 원문. */
1242
+ /** 채우기 기능 전용 — 어떤 셀의 수식을 dRow/dCol 만큼 이동한 자리에 맞게 참조를 옮긴 새 수식 원문을 돌려줍니다. / Fill-only — return a copy of a cell's formula with its relative refs shifted by dRow/dCol. */
989
1243
  offsetFormula(srcRowId: string, srcField: string, dRow: number, dCol: number): string;
990
- /** rowRef 는 flat/visual index(C0.2) 또는 stable id. maxDepth 초과 시 거부(announce, FR-10). */
1244
+ /** 행을 펼쳐 상세 패널을 엽니다. rowRef 는 화면 순서 인덱스 또는 안정적 id. 허용 겹수를 넘으면 거부됩니다. / Expand a row's detail panel. rowRef is a screen-order index or a stable id; rejected past the nesting limit. */
991
1245
  expandRow(rowRef: number | {
992
1246
  id: string;
993
1247
  }): void;
1248
+ /** 열려 있는 상세 패널을 접습니다. / Collapse an open detail panel. */
994
1249
  collapseRow(rowRef: number | {
995
1250
  id: string;
996
1251
  }): void;
1252
+ /** 상세 패널을 펼쳐져 있으면 접고, 접혀 있으면 폅니다. / Toggle a detail panel open/closed. */
997
1253
  toggleRow(rowRef: number | {
998
1254
  id: string;
999
1255
  }): void;
1256
+ /** 그 행의 상세 패널이 지금 펼쳐져 있는지. / Whether that row's detail panel is currently expanded. */
1000
1257
  isRowExpanded(rowRef: number | {
1001
1258
  id: string;
1002
1259
  }): boolean;
1260
+ /** 열려 있는 모든 상세 패널을 한 번에 접습니다. / Collapse every open detail panel at once. */
1003
1261
  collapseAllDetails(): void;
1004
- /** 펼쳐진 적 없으면 undefined. renderer 반환값 또는 자동 생성 서브그리드 인스턴스. */
1262
+ /** 그 행의 상세 패널 내용물(직접 그린 결과 또는 자동 생성된 자식 그리드). 한 번도 펼치지 않았으면 undefined. / The row's detail content (your rendered result or the auto-created child grid); undefined if never expanded. */
1005
1263
  getDetailInstance<D = any>(rowRef: number | {
1006
1264
  id: string;
1007
1265
  }): D | undefined;
1008
- /** FR-11: 컬럼/호스트 리사이즈 후 열린 패널 폭을 강제 재동기(보통은 재렌더가 자동 처리). */
1266
+ /** 컬럼·컨테이너 크기를 바꾼 뒤 열린 패널의 폭을 다시 맞춥니다(보통은 재렌더가 알아서 처리). / Re-sync open panel widths after a column/container resize (usually the re-render handles it). */
1009
1267
  resyncPanelWidths(): void;
1010
1268
  getChecked(): Array<{
1011
1269
  row: T;
@@ -1024,9 +1282,9 @@ export interface OpenGridInstance<T = any> {
1024
1282
  resetFilter(field?: string): void;
1025
1283
  getFilterState(): Record<string, FilterItem[]>;
1026
1284
  restoreFilter(state: Record<string, FilterItem[]>): void;
1027
- /** 지정 행들을 다른 그리드로 이동. 3단계 이벤트 + crossGridMapping 적용. */
1285
+ /** 지정한 행들을 다른 그리드로 옮깁니다(드래그·셔틀과 같은 경로). 옮기는 전·후·완료 3단계 이벤트가 나고 필드 매핑 규칙이 적용됩니다. / Move the given rows into another grid (same path as drag/shuttle). Fires the three-phase events and applies the field-mapping rule. */
1028
1286
  moveRowsTo(target: OpenGridInstance<T>, sourceIndexes: number[], targetIndex?: number): Promise<boolean>;
1029
- /** 체크된 행을 다른 그리드로 이동 (화살표 셔틀용) */
1287
+ /** 체크박스로 고른 행들을 다른 그리드로 옮깁니다(화살표 셔틀 버튼용). / Move the checkbox-selected rows into another grid (for the arrow-shuttle buttons). */
1030
1288
  moveCheckedTo(target: OpenGridInstance<T>): Promise<boolean>;
1031
1289
  freeze(columnCount: number): void;
1032
1290
  freezeRows(rowCount: number): void;
@@ -1053,23 +1311,23 @@ export interface OpenGridInstance<T = any> {
1053
1311
  resize(width?: number, height?: number): void;
1054
1312
  setTheme(theme: string): void;
1055
1313
  setThemeVar(varName: string, value: string): void;
1056
- /** R12b: 스킨(FORM 축) 전환 — data-og-skin 설정 + 인라인 form 사이트 재해석. 색 테마와 직교. */
1314
+ /** 스킨(형태 축)을 바꿉니다 — 모서리·테두리·여백 같은 "생김새"만 갈아 끼우고, 색 테마는 그대로 둡니다. / Switch the skin (form axis) — swaps the "shape" (corners, borders, spacing …) only, leaving the color theme untouched. */
1057
1315
  setSkin(skin: string): void;
1058
- /** R12b: 현재 스킨 id('default' = 오늘). */
1316
+ /** 지금 적용된 스킨 id('default' = 기본 생김새). / The currently applied skin id ('default' = stock look). */
1059
1317
  getSkin(): string;
1060
- /** R12b: FORM 축 단일 토큰 런타임 오버라이드(setThemeVar 의 형태-축 형제). 색 값은 거부. */
1318
+ /** 형태 축의 CSS 변수 하나만 즉석에서 바꿉니다(setThemeVar 의 형태 버전). 색 값을 넣으면 거부됩니다. / Override a single form-axis CSS variable at runtime (the form-axis sibling of setThemeVar). Color values are rejected. */
1061
1319
  setSkinVar(varName: string, value: string): void;
1062
- /** DD-11: 밀도(DENSITY 축) 전환 — data-og-density + --og-density-* 토큰(+행높이 미러, relayout). 미등록 never-throw. 색⊥형태⊥밀도⊥질감 직교. / DD-11: switch the density axis — additive data-og-density + --og-density-* tokens (row-height mirror + relayout). Never throws. */
1320
+ /** 밀도(행 간격)를 바꿉니다 — 촘촘/보통/여유처럼 행 높이와 여백을 통째로 조절합니다. 색·스킨과 따로 노는 별개 축이며, 없는 이름을 줘도 오류를 내지 않습니다. / Switch the density (row spacing) — compact/normal/roomy row heights and paddings. An independent axis from color/skin; never throws on an unknown name. */
1063
1321
  setDensity(name: string): void;
1064
- /** DD-11: 질감(TEXTURE 축) 전환 — data-og-texture + --og-texture-* 토큰(배경 페인트만, relayout 없음). 미등록 never-throw. / DD-11: switch the texture axis — additive data-og-texture + --og-texture-* tokens (paint only, no relayout). Never throws. */
1322
+ /** 질감(배경 패턴)을 바꿉니다 — 배경 페인트만 입히고 크기 재계산은 하지 않습니다. 없는 이름을 줘도 오류를 내지 않습니다. / Switch the texture (background pattern) — paints the background only, no relayout. Never throws on an unknown name. */
1065
1323
  setTexture(name: string): void;
1066
- /** UI 로케일 전환 — 크롬+가시창 재렌더 + emit('localeChange'). 미등록 로케일은 never-throw. */
1324
+ /** UI 문구의 언어(로케일)를 바꾸고 화면을 다시 그립니다. 등록되지 않은 로케일을 줘도 오류를 내지 않습니다. / Switch the UI language (locale) and re-render. Never throws on an unregistered locale. */
1067
1325
  setLocale(locale: string): void;
1068
- /** 현재 인스턴스 로케일 id. */
1326
+ /** 이 그리드에 지금 적용된 로케일 id. / The locale id currently applied to this grid. */
1069
1327
  getLocale(): string;
1070
- /** 이 인스턴스만 단일 메시지 오버라이드(setIcon 동형, 첫 호출 시 child 지연생성). */
1328
+ /** 이 그리드에서만 특정 문구 하나를 다른 말로 바꿉니다. / Override a single UI message for this grid only. */
1071
1329
  setMessage(key: LocaleMessageKey | string, value: MessageValue): OpenGridInstance<T>;
1072
- /** 메시지 해석(오버라이드 우선 → 활성 로케일 → ko → 키). 절대 throw 안 함. */
1330
+ /** 키에 해당하는 문구를 찾아 돌려줍니다(개별 오버라이드 → 활성 로케일 → 한국어 → 키 순). 오류를 내지 않습니다. / Resolve a message by key (per-message override → active locale → Korean → the key itself). Never throws. */
1073
1331
  t(key: LocaleMessageKey | string, params?: Record<string, string | number>): string;
1074
1332
  destroy(): void;
1075
1333
  setOptions(opts: Partial<GridOptions<T>>): void;
@@ -1164,7 +1422,17 @@ export interface TriggerContext<TResult = any> {
1164
1422
  */
1165
1423
  cancel(): void;
1166
1424
  }
1167
- /** 트리거 핸들러 함수 타입 / Trigger handler function type */
1425
+ /**
1426
+ * 트리거로 등록하는 핸들러 함수의 형태입니다. 작업의 맥락(TriggerContext)을 인자로 받아,
1427
+ * 작업 전이라면 검증·취소하고 작업 후라면 결과를 확인하는 등의 일을 합니다.
1428
+ * / The shape of a handler you register as a trigger. It receives the operation's context
1429
+ * (TriggerContext) — validate/cancel before, or inspect the result after.
1430
+ */
1168
1431
  export type TriggerHandler<TResult = any> = (ctx: TriggerContext<TResult>) => void;
1169
- /** 지원되는 트리거 이벤트명 / Supported trigger event names */
1432
+ /**
1433
+ * 트리거를 걸 수 있는 이벤트 이름들. 형식은 '시점:작업' 입니다 — 'before:작업'은 그 작업이 실행되기
1434
+ * 직전(여기서 취소 가능), 'after:작업'은 끝난 직후, 'complete'는 어떤 작업이든 끝난 뒤 공통으로 호출됩니다.
1435
+ * / The event names you can attach triggers to, in 'phase:operation' form — 'before:*' fires just
1436
+ * before the operation (cancelable there), 'after:*' just after, and 'complete' after any operation.
1437
+ */
1170
1438
  export type TriggerEvent = 'before:setData' | 'after:setData' | 'before:insertRow' | 'after:insertRow' | 'before:deleteRow' | 'after:deleteRow' | 'before:writeCell' | 'after:writeCell' | 'before:applyColumns' | 'after:applyColumns' | 'before:orderBy' | 'after:orderBy' | 'before:setFilter' | 'after:setFilter' | 'before:groupBy' | 'after:groupBy' | 'complete';