open-grid 1.2.0 → 1.2.1

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

@@ -1,14 +1,17 @@
 import { FilterItem } from './types.js';
 /** i18n: 필터 셀렉트 라벨 해석기(주입 없으면 전역 t). / i18n: filter-select label resolver (global t when not injected). */
 export type FilterSelectT = (key: string, params?: Record<string, string | number>) => string;
+/** 필터 셀렉트 옵션(값/표시 텍스트). / Filter-select option (value/display text). */
 export interface FilterSelectOption {
+    /** 필터·선택에 사용할 값. / Value used for filtering/selection. */
     value: string;
+    /** 화면에 표시할 텍스트. / Text shown on screen. */
     text: string;
 }
 /**
- * 캐스케이딩 필터 셀렉트 컬럼 정의.
+ * 캐스케이딩 필터 셀렉트 컬럼 정의. / Cascading filter-select column definition.
  *
- * ### 데이터 공급 방식 (택 1)
+ * ### 데이터 공급 방식 (택 1) / Data supply (pick one)
  *
  * **A. JSON 배열 바인딩** (권장)
  * ```ts
@@ -30,30 +33,31 @@ export interface FilterSelectOption {
  * ```
  */
 export interface FilterSelectColumn {
-    /** 캐스케이딩 식별자 / 기본 필터 키 */
+    /** 캐스케이딩 식별자 / 기본 필터 키. / Cascading identifier / default filter key. */
     field: string;
-    /** 화면 표시 라벨 */
+    /** 화면 표시 라벨. / Display label. */
     label: string;
-    /** 바인딩할 JSON 배열 */
+    /** 바인딩할 JSON 배열. / JSON array to bind. */
     data?: any[];
-    /** data[]에서 option value로 사용할 키 */
+    /** data[] 에서 option value 로 사용할 키. / Key in data[] used as the option value. */
     valueKey?: string;
-    /** data[]에서 화면 표시 text로 사용할 키 (미지정 시 valueKey 사용) */
+    /** data[] 에서 화면 표시 text 로 사용할 키(미지정 시 valueKey 사용). / Key in data[] used as display text (falls back to valueKey). */
     textKey?: string;
     /**
-     * 그리드 행 데이터에서 실제 필터링할 키.
-     * 미지정 시 `field` 값 그대로 사용.
+     * 그리드 행 데이터에서 실제 필터링할 키. 미지정 시 `field` 값 그대로 사용.
+     * / Key actually filtered against grid row data; falls back to `field`.
      *
      * @example
-     * // 그리드 row.category === selectedValue 로 필터링
+     * // 그리드 row.category === selectedValue 로 필터링 / filter where row.category === selectedValue
      * filterKey: 'category'
      */
     filterKey?: string;
+    /** 정적 옵션 배열(data 대신 사용). / Static option array (used instead of data). */
     options?: FilterSelectOption[];
-    /** 부모 컬럼의 field 명 */
+    /** 부모 컬럼의 field 명. / Parent column's field name. */
     dependsOn?: string;
     /**
-     * 자식 data[]에서 부모 선택값과 비교할 키.
+     * 자식 data[] 에서 부모 선택값과 비교할 키. / Key in the child data[] compared against the parent's selected value.
      *
      * @example
      * // brandList.filter(b => b.catCode === parentSelectedValue)
@@ -61,13 +65,23 @@ export interface FilterSelectColumn {
      */
     dependsOnKey?: string;
 }
+/** 필터 셀렉트 패널 구성. / Filter-select panel configuration. */
 export interface FilterSelectConfig {
+    /** 캐스케이딩 컬럼 정의 배열. / Cascading column definitions. */
     columns: FilterSelectColumn[];
-    /** fieldset 제목 (기본: '필터') */
+    /** fieldset 제목(기본: 로케일 'filter.legend'). / fieldset legend (default: locale 'filter.legend'). */
     legend?: string;
 }
 type FilterFn = (field: string, items: FilterItem[]) => void;
 type ResetFn = (field?: string) => void;
+/**
+ * 캐스케이딩 필터 셀렉트 패널. / Cascading filter-select panel.
+ *
+ * 그리드 헤더 앞에 fieldset 형태의 셀렉트 필터를 삽입하고, 부모→자식 종속(캐스케이딩)
+ * 옵션 재계산과 그리드 필터 콜백을 배선한다.
+ * / Inserts a fieldset of select filters ahead of the grid header and wires parent→child cascading
+ * option recalculation to the grid filter callbacks.
+ */
 export declare class FilterSelectPanel {
     private _el;
     private _selects;
@@ -77,6 +91,14 @@ export declare class FilterSelectPanel {
     private _onFilter;
     private _onReset;
     private _t;
+    /**
+     * @param container - 패널을 삽입할 컨테이너(그리드 헤더 앞에 prepend) / Container to insert the panel into (prepended before the grid header)
+     * @param config - 패널 구성 / Panel configuration
+     * @param onFilter - 필터 적용 콜백(field, items) / Filter-apply callback (field, items)
+     * @param onReset - 필터 해제 콜백(field?) / Filter-reset callback (field?)
+     * @param gridId - aria-controls 로 연결할 그리드 id(선택) / Grid id to link via aria-controls (optional)
+     * @param t - 로케일 해석기(미주입 시 전역 t) / Locale resolver (global t when not injected)
+     */
     constructor(container: HTMLElement, config: FilterSelectConfig, onFilter: FilterFn, onReset: ResetFn, gridId?: string, t?: FilterSelectT);
     /**
      * 컬럼의 옵션 목록을 계산한다.
@@ -92,7 +114,9 @@ export declare class FilterSelectPanel {
      */
     private _cascade;
     private _reset;
+    /** 모든 필터 선택을 초기화한다. / Reset all filter selections. */
     reset(): void;
+    /** 패널을 DOM 에서 제거한다. / Remove the panel from the DOM. */
     destroy(): void;
 }
 export {};

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

@@ -2,16 +2,33 @@ import { ColumnLayout } from './ColumnLayout.js';
 import { DataLayer } from './DataLayer.js';
 import { Pagination } from './Pagination.js';
 import { VirtualScroll } from './VirtualScroll.js';
+/**
+ * FindBarManager 의존성 주입 인터페이스. / Dependency-injection interface for FindBarManager.
+ */
 export interface FindBarDeps<T extends Record<string, any>> {
+    /** 현재 컬럼 레이아웃(검색 대상 필드 조회용). / Current column layout (for resolving searchable fields). */
     getColLayout: () => ColumnLayout<T>;
+    /** 그리드 데이터 레이어(찾기/필터 적용 대상). / Grid data layer to apply the find filter against. */
     getData: () => DataLayer<T>;
+    /** 현재 활성 컬럼 필터(찾기와 함께 재적용). / Currently active column filters (reapplied alongside the find filter). */
     getFilters: () => Record<string, any[]>;
+    /** 가상 스크롤 인스턴스(행수 갱신용). 없으면 `null`. / Virtual-scroll instance (for updating row count); `null` if absent. */
     getVs: () => VirtualScroll | null;
+    /** 페이지네이션 인스턴스(행수 갱신용). 없으면 `null`. / Pagination instance (for updating row count); `null` if absent. */
     getPagination: () => Pagination | null;
+    /** 필터 적용 후 그리드 재렌더를 트리거. / Triggers a grid re-render after the filter is applied. */
     doRender: () => void;
     /** i18n: 메시지 해석(라벨/placeholder/aria/카운트 배지). / i18n: resolve labels/placeholder/aria/count badge. */
     t: (key: string, params?: Record<string, string | number>) => string;
 }
+/**
+ * 그리드 상단 찾기(find) 바 관리자. / Manages the grid's top find bar.
+ *
+ * 입력값을 표시 중인 모든 컬럼에 대한 부분 일치 필터로 변환해 {@link DataLayer}에
+ * 적용하고, 가상 스크롤/페이지네이션의 행 수를 함께 갱신한다.
+ * / Turns the input value into a substring-match filter across all visible columns,
+ * applies it via {@link DataLayer}, and keeps virtual-scroll/pagination row counts in sync.
+ */
 export declare class FindBarManager<T extends Record<string, any> = any> {
     private _bar;
     private _input;
@@ -21,11 +38,20 @@ export declare class FindBarManager<T extends Record<string, any> = any> {
     private _filter;
     private _d;
     constructor(deps: FindBarDeps<T>);
+    /** 현재 찾기 입력값. / Current find-bar input value. */
     get findFilter(): string;
+    /**
+     * 찾기 바 DOM 을 생성하고 컨테이너 최상단에 삽입한다. / Build the find-bar DOM and insert it at the top of the container.
+     *
+     * @param container - 그리드 컨테이너 엘리먼트 / Grid container element
+     */
     init(container: HTMLElement): void;
     /** i18n: 상주 크롬 라벨을 활성 로케일로 다시 그린다(setLocale 경로). / i18n: repaint resident chrome labels in the active locale (setLocale path). */
     refreshLabels(): void;
+    /** 찾기 바를 표시하고 입력에 포커스한다. / Show the find bar and focus the input. */
     open(): void;
+    /** 찾기 바를 숨기고 필터를 해제한다. / Hide the find bar and clear the filter. */
     close(): void;
+    /** @internal 현재 찾기 필터를 데이터 레이어에 적용하고 재렌더한다. / Applies the current find filter to the data layer and re-renders. */
     private _apply;
 }

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

@@ -1,25 +1,39 @@
 import { DataLayer } from './DataLayer.js';
-/** flat 한 행이 무엇을 가리키는지 판별하는 참조 정보(C0.3). */
+/**
+ * flat 한 행이 무엇을 가리키는지 판별하는 참조 정보(C0.3).
+ * / Reference info identifying what a flat row points to (C0.3).
+ */
 export interface FlatRowRef {
+    /** 행 종류(데이터/그룹/트리/디테일 헤드·필러). / Row kind (data/group/tree/detail head·filler). */
     kind: 'data' | 'group' | 'tree' | 'detailHead' | 'detailFiller';
-    /** kind==='data'|'tree' 일 때 stable id(DataLayer 가 부여한 rowId 필드값). */
+    /** kind==='data'|'tree' 일 때 stable id(DataLayer 가 부여한 rowId 필드값). / Stable id when kind is 'data'|'tree' (the rowId field value assigned by DataLayer). */
     rowId?: string;
-    /** kind==='data' 일 때 DataLayer 원본(_data) 인덱스. */
+    /** kind==='data' 일 때 DataLayer 원본(_data) 인덱스. / DataLayer source (_data) index when kind is 'data'. */
     dataIndex?: number;
-    /** 정렬/필터 반영된 논리 순서. plain 모드(backing 미교체)에서만 flatIndex 와 1:1 대응. */
+    /** 정렬/필터 반영된 논리 순서. plain 모드(backing 미교체)에서만 flatIndex 와 1:1 대응. / Logical order after sort/filter; equals flatIndex 1:1 only in plain mode (backing not replaced). */
     displayIndex?: number;
 }
 /** flat 배열을 구성하는 원소(실데이터 행 T, GroupRow, 또는 TreeNode) — 내부 전용. */
 type FlatItem = any;
-/** group/tree 등이 baseline backing 을 통째로 교체할 때 쓰는 provider. null = plain 으로 복귀. */
+/** group/tree 등이 baseline backing 을 통째로 교체할 때 쓰는 provider. null = plain 으로 복귀. / Provider used by group/tree to replace the baseline backing wholesale; null = revert to plain. */
 export type FlatBackingProvider = (() => FlatItem[]) | null;
-/** (Phase 0: 등록 지점만 제공, 소비자 없음) 합성 후단에서 flat 배열을 변형하는 훅 — F2 detail splice 용. */
+/** 합성 후단에서 flat 배열을 변형하는 훅 — F2 detail splice 용. / Hook that transforms the flat array at the tail of composition — for F2 detail splice. */
 export type FlatSpliceFn = (flat: FlatItem[]) => FlatItem[];
+/** FlatRowModel 의존성 주입. / FlatRowModel dependency injection. */
 export interface FlatRowModelDeps {
+    /** 현재 DataLayer 를 반환하는 getter. / Getter returning the current DataLayer. */
     getDataLayer: () => DataLayer<any>;
-    /** DataLayer 가 각 행에 부여하는 안정 rowId 필드명(OpenGrid 의 ROW_ID_FIELD, 기본 '_ogRowId'). */
+    /** DataLayer 가 각 행에 부여하는 안정 rowId 필드명(OpenGrid 의 ROW_ID_FIELD, 기본 '_ogRowId'). / Stable rowId field name assigned by DataLayer (OpenGrid's ROW_ID_FIELD, default '_ogRowId'). */
     rowIdField: string;
 }
+/**
+ * flat/visual index ↔ data 리졸버(baseline 공통 인프라). / flat/visual index ↔ data resolver (baseline shared infra).
+ *
+ * plain rows 를 기본 backing 으로 두고, group/tree 는 setBacking 으로 backing 을 교체하며,
+ * F2 는 registerSplice 로 합성 후단에 detail 의사행을 끼워 넣는다(합성 체인은 단방향).
+ * / Uses plain rows as the default backing; group/tree replace the backing via setBacking, and F2 inserts
+ * detail pseudo-rows at the tail of composition via registerSplice (the composition chain is one-directional).
+ */
 export declare class FlatRowModel {
     private _d;
     /** group/tree 가 등록한 backing override. null 이면 plain(DataLayer.getData()). */
@@ -30,24 +44,53 @@ export declare class FlatRowModel {
     private _revIndexSrc;
     constructor(deps: FlatRowModelDeps);
     /**
-     * group/tree 등 baseline backing 을 통째로 교체하는 등록점.
-     * provider=null 이면 plain(DataLayer 표시 순서)으로 복귀.
+     * group/tree 등 baseline backing 을 통째로 교체하는 등록점. provider=null 이면 plain(DataLayer 표시 순서)으로 복귀.
+     * / Registration point that replaces the baseline backing wholesale (group/tree); provider=null reverts to plain (DataLayer display order).
+     *
+     * @param provider - backing 공급 함수 또는 null / Backing provider function or null
      */
     setBacking(provider: FlatBackingProvider): void;
     /**
-     * (Phase 0: 등록 지점만 제공, 미소비) F2 DetailManager 가 합성 후단에 detail
-     * head/filler pseudo-row 를 끼워 넣을 변환기를 등록한다. 등록 순서대로 순차 적용.
+     * F2 DetailManager 가 합성 후단에 detail head/filler pseudo-row 를 끼워 넣을 변환기를 등록한다. 등록 순서대로 순차 적용.
+     * / Register a transformer that F2 DetailManager uses to insert detail head/filler pseudo-rows at the tail of composition; applied in registration order.
+     *
+     * @param fn - flat 배열 변환 함수 / Flat-array transform function
      */
     registerSplice(fn: FlatSpliceFn): void;
+    /** 합성 완료된 flat 행 수. / Count of composed flat rows. */
     count(): number;
     /**
      * 합성 완료된 flat 배열 원본을 노출한다(F2 렌더 배선 소비 — GridRenderer.renderBody 가 이 배열을
      * `groupFlatRows` 자리에 그대로 넘겨받아 detail head/filler 를 렌더한다). 호출측은 결과를
      * 변경하지 않는다(내부 backing/splice 산출물을 그대로 반환).
+     * / Expose the composed flat array (consumed by F2 render wiring — GridRenderer.renderBody takes it in the
+     * `groupFlatRows` slot to render detail head/filler). Callers must not mutate the result (it returns the
+     * internal backing/splice output as-is).
+     *
+     * @returns 합성된 flat 배열(변경 금지) / The composed flat array (do not mutate)
      */
     getFlatArray(): FlatItem[];
+    /**
+     * flat index 가 가리키는 행의 참조 정보를 해소한다(C0.3 쓰기 안전).
+     * / Resolve the reference info for the row at a flat index (C0.3 write-safety).
+     *
+     * @param flatIndex - 합성된 flat 배열의 인덱스 / Index into the composed flat array
+     * @returns 행 참조 정보 / Row reference info
+     */
     resolveFlatRow(flatIndex: number): FlatRowRef;
+    /**
+     * rowId → 현재 flat index. 없으면 -1. / rowId → current flat index; -1 if absent.
+     *
+     * @param rowId - 조회할 stable rowId / Stable rowId to look up
+     * @returns flat index 또는 -1 / Flat index or -1
+     */
     flatIndexOfRowId(rowId: string): number;
+    /**
+     * flat index → rowId(data/tree 행일 때만). 그 외 null. / flat index → rowId (only for data/tree rows); null otherwise.
+     *
+     * @param flatIndex - 합성된 flat 배열의 인덱스 / Index into the composed flat array
+     * @returns rowId 또는 null / rowId or null
+     */
     rowIdOfFlat(flatIndex: number): string | null;
     private _flat;
     private _invalidate;

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

@@ -1,17 +1,69 @@
 import { ColumnLayout } from './ColumnLayout.js';
+/**
+ * FooterManager 의존성 주입 인터페이스. / Dependency-injection interface for FooterManager.
+ */
 export interface FooterDeps<T extends Record<string, any>> {
+    /** 요약 대상 전체 행 데이터. / Full row data to summarize. */
     getData: () => T[];
+    /** 현재 컬럼 레이아웃(가시 리프 컬럼 조회용). / Current column layout (for resolving visible leaf columns). */
     getColLayout: () => ColumnLayout<T>;
+    /** 컬럼별 현재 폭(px) 배열. / Current per-column widths (px). */
     getColWidths: () => number[];
+    /** 그리드 옵션 스냅샷(`footer`/`footerHeight`/`footerPosition` 등 포함). / Snapshot of grid options (includes `footer`, `footerHeight`, `footerPosition`, etc.). */
     getOptions: () => any;
+    /** 푸터 바를 삽입할 그리드 컨테이너 엘리먼트. / Grid container element into which the footer bar is inserted. */
     getContainer: () => HTMLElement;
-    /** Phase 2: OverrideKernel.getStrategy 주입(슬롯 summaryOp 도달용). */
+    /** Phase 2: OverrideKernel.getStrategy 주입(슬롯 summaryOp 도달용). / Phase 2: injected via OverrideKernel.getStrategy (reaches the `summaryOp` slot). */
     getStrategy?: <F extends Function>(slot: string, fallback: F) => F;
 }
+/**
+ * 그리드 하단 요약 푸터(합계/평균/개수 등) 관리자. / Manages the grid's summary footer bar (sum/avg/count/…).
+ *
+ * `options.footer` 정의를 읽어 각 컬럼 집계값을 계산하고, 컬럼 폭에 맞춘 셀로
+ * 렌더한다. `summaryOp` override 슬롯으로 MEDIAN/STDEV 등 커스텀 집계를 가로챌 수 있다.
+ * / Reads the `options.footer` definitions to compute per-column aggregates and renders
+ * them as cells aligned to column widths. The `summaryOp` override slot lets custom
+ * aggregates (MEDIAN/STDEV/…) intercept the default SUM/AVG/COUNT/MAX/MIN switch.
+ */
 export declare class FooterManager<T extends Record<string, any> = any> {
     private _d;
     constructor(deps: FooterDeps<T>);
+    /**
+     * 숫자를 포맷 문자열에 따라 표시용 문자열로 변환한다. / Format a number into a display string according to a format string.
+     *
+     * `fmt` 미지정 시 반올림 후 `ko-KR` 로케일 구분기호로 표기한다. 지정 시 숫자 토큰
+     * 앞뒤의 접두/접미(통화 기호 등)를 분리하고, `#`/`,` 포함 여부로 천단위 구분기호
+     * 사용을, 소수부 자릿수로 반올림 정밀도를 결정한다.
+     * / Without `fmt`, rounds and formats using `ko-KR` locale separators. With `fmt`,
+     * splits off any prefix/suffix around the numeric token (e.g. a currency symbol),
+     * uses `#`/`,` presence to decide thousands-separator use, and the decimal-token
+     * length to decide rounding precision.
+     *
+     * @param value - 포맷할 값 / Value to format
+     * @param fmt - 숫자 포맷 문자열(예: `'#,##0.00'`, 통화 접두/접미 포함 가능) / Number format string (e.g. `'#,##0.00'`, may include a currency prefix/suffix)
+     * @returns 포맷된 표시 문자열 / The formatted display string
+     */
     fmtNum(value: number, fmt?: string): string;
+    /**
+     * `options.footer` 정의별 집계값을 계산한다. / Compute the aggregate value for each `options.footer` definition.
+     *
+     * 수식 에러 셀(`#REF` 등)은 집계에서 제외한다(0 취급 아님 — 값 오염 차단, C11).
+     * `summaryOp` override 슬롯이 숫자를 반환하면 그 값을 쓰고(예: MEDIAN/STDEV),
+     * `null` 을 반환하면 기본 SUM/AVG/COUNT/MAX/MIN 분기로 폴백한다.
+     * / Formula-error cells (`#REF`, …) are excluded from aggregation (not treated as 0 —
+     * prevents value contamination, C11). If the `summaryOp` override slot returns a
+     * number (e.g. for MEDIAN/STDEV), that value is used; returning `null` falls back to
+     * the default SUM/AVG/COUNT/MAX/MIN branch.
+     *
+     * @returns 정의 순서대로 `{ _field, _value, _formatted }` 배열 / Array of `{ _field, _value, _formatted }`, in definition order
+     */
     computeValues(): any[];
+    /**
+     * 요약 푸터 바를 (재)렌더한다. / (Re)render the summary footer bar.
+     *
+     * 기존 `.og-footer-bar` 를 제거 후 새로 그리며, `options.footerPosition` 에 따라
+     * 컨테이너 상단 또는 하단에 삽입한다. / Removes any existing `.og-footer-bar` and
+     * redraws it, inserting at the top or bottom of the container per `options.footerPosition`.
+     */
     render(): void;
 }

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

@@ -8,74 +8,203 @@ import { FormulaErrorCode, FormulaGridAccessor } from './formula/types.js';
  * R7(§3.1 C9, §6-R7): F3 수식 표면(accessor 조립·recalc flush·에러 표현 + 공개 수식 API)을
  * `OpenGrid` God object 에서 **동작 불변**으로 옮긴 것. `OpenGrid` 는 얇은 위임 공개 메서드만
  * 남긴다(공개 API 불변 — R0 `public_api_surface.txt` 동결).
+ * / R7 (§3.1 C9, §6-R7): F3's formula surface (accessor assembly, recalc flush, error surfacing,
+ * plus the public formula API) moved out of the `OpenGrid` God object with **behavior unchanged**.
+ * `OpenGrid` retains only thin delegating public methods (public API frozen — R0
+ * `public_api_surface.txt`).
  *
  * 스트랭글러 원칙(A2): `RecalcCoordinator`(`formula/` 헤드리스 코어)는 여전히 `OpenGrid` 가
  * 소유·재생성(setData 시 rowId 재발급 대응)하며, 이 컨트롤러에는 `*Deps` 클로저 역전 패턴으로
  * **주입**만 된다 — `getRecalc()` 는 재할당(resetFormulaState)을 견디는 지연 getter 다.
  * `RecalcCoordinator`/`FormulaGraph`/`FormulaEvaluator` 자체는 한 줄도 수정하지 않는다(불변 보존).
+ * / Strangler-fig principle (A2): `RecalcCoordinator` (the `formula/` headless core) is still
+ * owned and re-created by `OpenGrid` (to handle rowId reassignment on setData), and is only
+ * **injected** into this controller via the `*Deps` closure-inversion pattern — `getRecalc()` is a
+ * lazy getter that survives reassignment (resetFormulaState). `RecalcCoordinator`/`FormulaGraph`/
+ * `FormulaEvaluator` themselves are never modified (preserved as-is).
  *
  * ⚠️ 네이밍: root `src/core/FormulaEngine.ts` 와 `src/core/formula/` 패키지는 별개다. 이 컨트롤러는
  * `formula/` 패키지(RecalcCoordinator)에만 배선하며 root `FormulaEngine.ts` 와는 무관하다(병합 금지).
+ * / ⚠️ Naming: root `src/core/FormulaEngine.ts` and the `src/core/formula/` package are distinct.
+ * This controller only wires to the `formula/` package (RecalcCoordinator) and is unrelated to
+ * root `FormulaEngine.ts` (never merge them).
+ */
+/**
+ * FormulaController 가 OpenGrid 서브시스템을 읽고 쓰기 위해 주입받는 클로저 묶음.
+ * / Closures injected into FormulaController so it can read and write OpenGrid subsystem state
+ * without owning it directly.
  */
 export interface FormulaControllerDeps<T extends Record<string, any> = any> {
     getData: () => DataLayer<T>;
     getColLayout: () => ColumnLayout<T>;
     getFlatModel: () => FlatRowModel;
-    /** OpenGrid 가 소유하는 RecalcCoordinator. setData 시 재생성되므로 지연 getter 로 읽는다. */
+    /** OpenGrid 가 소유하는 RecalcCoordinator. setData 시 재생성되므로 지연 getter 로 읽는다.
+     * / The RecalcCoordinator owned by OpenGrid. Read via a lazy getter since it is re-created on setData. */
     getRecalc: () => RecalcCoordinator;
-    /** writeCell 이 적립한 dirty seed 집합(OpenGrid 소유). flushRecalc 가 소비·clear 한다. */
+    /** writeCell 이 적립한 dirty seed 집합(OpenGrid 소유). flushRecalc 가 소비·clear 한다.
+     * / The dirty-seed set accumulated by writeCell (owned by OpenGrid). Consumed and cleared by flushRecalc. */
     getDirtySeeds: () => Set<string>;
     getOptions: () => Required<GridOptions<T>>;
-    /** EventEmitter fan(this.emit) — 'formulaRecalc'/'formulaError'/'formulaChange'. */
+    /** EventEmitter fan(this.emit) — 'formulaRecalc'/'formulaError'/'formulaChange'.
+     * / EventEmitter fan-out (this.emit) for 'formulaRecalc'/'formulaError'/'formulaChange'. */
     emit: (event: string, payload?: any) => void;
-    /** aria-live announce(C8.1 공용 인프라). */
+    /** aria-live announce(C8.1 공용 인프라). / aria-live announce (C8.1 shared infrastructure). */
     announce: (msg: string) => void;
     /** i18n: 수식 오류 announce/셀 라벨 해석(formulaError.* 통합 키). / i18n: resolve formula error announce/labels. */
     t: (key: string, params?: Record<string, string | number>) => string;
-    /** 현재 가시 범위 렌더(this._doRender(...this._visRange())). afterRecalc 가 !skipRender 시 유발. */
+    /** 현재 가시 범위 렌더(this._doRender(...this._visRange())). afterRecalc 가 !skipRender 시 유발.
+     * / Renders the currently visible range (this._doRender(...this._visRange())). Triggered by
+     * afterRecalc when !skipRender. */
     doRenderWindow: () => void;
 }
+/**
+ * F3 셀 수식 컨트롤러. / F3 cell formula controller.
+ *
+ * `RecalcCoordinator`(헤드리스 의존성 그래프+평가기)를 그리드 서브시스템(FlatRowModel/ColumnLayout/
+ * DataLayer)에 배선하고, 재계산 결과를 `formulaRecalc`/`formulaError`/`formulaChange` 이벤트로
+ * 표면화하며, `setCellFormula` 등 공개 수식 API 를 제공한다. / Wires `RecalcCoordinator` (the
+ * headless dependency graph + evaluator) into the grid subsystems (FlatRowModel/ColumnLayout/
+ * DataLayer), surfaces recalculation results as `formulaRecalc`/`formulaError`/`formulaChange`
+ * events, and exposes the public formula API (`setCellFormula`, etc.).
+ */
 export declare class FormulaController<T extends Record<string, any> = any> {
     private _deps;
     constructor(deps: FormulaControllerDeps<T>);
-    /** writeCell 이 적립한 dirty seed 를 1회 onValuesChanged 로 소비하고 formulaRecalc 를 emit. */
+    /** writeCell 이 적립한 dirty seed 를 1회 onValuesChanged 로 소비하고 formulaRecalc 를 emit.
+     * / Consumes the dirty seeds accumulated by writeCell in a single onValuesChanged call and
+     * emits formulaRecalc. */
     flushRecalc(): void;
     /**
      * RecalcCoordinator 호출 결과를 표면화: formulaError 는 onFormulaError 콜백에서 이미 개별
      * emit 되므로 여기선 배치당 1회 formulaRecalc 만 emit(C2.2 개명, `recalc`→`formulaRecalc`).
      * Spike-A §8 교훈: 폐포가 큰 재계산은 large 플래그로 표시(가이드 문서화/모니터링용).
+     * / Surfaces a RecalcCoordinator call result: `formulaError` is already emitted individually
+     * from the onFormulaError callback, so this only emits one `formulaRecalc` per batch (C2.2
+     * rename, `recalc` → `formulaRecalc`). Spike-A §8 lesson: recalculations with a large
+     * dependency closure are flagged via `large` (for docs/monitoring).
+     *
+     * @param summary - RecalcCoordinator 가 반환한 재계산 결과 요약 / Recalculation result summary returned by RecalcCoordinator
+     * @param opts - `skipRender` 지정 시 재렌더를 생략(호출측이 배치 처리 중) / When `skipRender` is set, skips the re-render (caller is batching)
      */
     afterRecalc(summary: RecalcSummary, opts?: {
         skipRender?: boolean;
     }): void;
+    /** 수식 평가 오류를 표면화: `formulaError` emit + aria-live 공지. / Surface a formula evaluation
+     * error: emits `formulaError` and announces it via aria-live.
+     *
+     * @param rowId - 오류가 발생한 셀의 행 stable id / Stable id of the row where the error occurred
+     * @param field - 오류가 발생한 컬럼 field / Column field where the error occurred
+     * @param error - 수식 오류 코드(`#REF`/`#CYCLE` 등) / Formula error code (`#REF`, `#CYCLE`, etc.)
+     */
     handleFormulaError(rowId: string, field: string, error: FormulaErrorCode): void;
     private _formulaErrorMessageKo;
-    /** F3 accessor(C0/C0.5/C1) — FlatRowModel + ColumnLayout.visibleLeaves + DataLayer(rowId 기반)만 본다. */
+    /** F3 accessor(C0/C0.5/C1) — FlatRowModel + ColumnLayout.visibleLeaves + DataLayer(rowId 기반)만 본다.
+     * / F3 accessor (C0/C0.5/C1) — reads only through FlatRowModel, ColumnLayout.visibleLeaves, and
+     * DataLayer (rowId-based).
+     *
+     * @returns RecalcCoordinator 가 그리드를 읽는 데 쓰는 accessor / Accessor RecalcCoordinator uses to read the grid
+     */
     buildAccessor(): FormulaGridAccessor;
+    /**
+     * 셀에 수식을 설정한다(flat rowIndex 기준). / Set a formula on a cell (keyed by flat rowIndex).
+     *
+     * @param rowIndex - 대상 행의 flat index / Flat index of the target row
+     * @param field - 대상 컬럼 field / Target column field
+     * @param formula - 설정할 수식 원문(예: `=A1+B1`) / Formula source to set (e.g. `=A1+B1`)
+     * @example
+     * grid.setCellFormula(0, 'total', '=price*qty');
+     */
     setCellFormula(rowIndex: number, field: string, formula: string): void;
+    /** stable rowId 기준으로 셀 수식을 설정한다(F1 fill 등 rowId 를 이미 아는 호출자용).
+     * / Set a cell formula keyed by stable rowId (for callers — e.g. F1 fill — that already know the rowId).
+     *
+     * @param rowId - 대상 행의 stable id / Stable id of the target row
+     * @param field - 대상 컬럼 field / Target column field
+     * @param formula - 설정할 수식 원문 / Formula source to set
+     * @param rowIndexHint - 이미 알고 있는 flat index(이벤트 payload 용, 생략 시 재조회) / Known flat index for the event payload (re-resolved if omitted)
+     */
     setCellFormulaByRowId(rowId: string, field: string, formula: string, rowIndexHint?: number): void;
+    /** 셀에 설정된 수식 원문을 조회한다(없으면 `null`). / Get the formula source set on a cell (or `null` if none).
+     *
+     * @param rowIndex - 대상 행의 flat index / Flat index of the target row
+     * @param field - 대상 컬럼 field / Target column field
+     * @returns 수식 원문, 없으면 `null` / Formula source, or `null`
+     */
     getCellFormula(rowIndex: number, field: string): string | null;
+    /** 셀에 수식이 설정돼 있는지 여부. / Whether a cell has a formula set on it.
+     *
+     * @param rowIndex - 대상 행의 flat index / Flat index of the target row
+     * @param field - 대상 컬럼 field / Target column field
+     * @returns 수식이 있으면 true / True if the cell has a formula
+     */
     hasCellFormula(rowIndex: number, field: string): boolean;
+    /** 셀의 수식을 제거한다(값 셀로 되돌리며, 남은 의존 셀은 재계산). / Remove a cell's formula
+     * (reverting it to a plain value cell; remaining dependents are recalculated).
+     *
+     * @param rowIndex - 대상 행의 flat index / Flat index of the target row
+     * @param field - 대상 컬럼 field / Target column field
+     */
     clearCellFormula(rowIndex: number, field: string): void;
+    /** 셀의 마지막 수식 평가 오류를 조회한다(정상이면 `null`). / Get a cell's last formula evaluation error (`null` if healthy).
+     *
+     * @param rowIndex - 대상 행의 flat index / Flat index of the target row
+     * @param field - 대상 컬럼 field / Target column field
+     * @returns 오류 코드, 없으면 `null` / Error code, or `null`
+     */
     getCellError(rowIndex: number, field: string): FormulaErrorCode | null;
+    /** 이 셀을 참조하는(값이 바뀌면 재계산되는) 셀 목록. / Cells that reference this cell (recalculated when it changes).
+     *
+     * @param rowIndex - 대상 행의 flat index / Flat index of the target row
+     * @param field - 대상 컬럼 field / Target column field
+     * @returns 의존 셀들의 rowIndex/field 목록 / List of dependent cells' rowIndex/field
+     */
     getDependents(rowIndex: number, field: string): Array<{
         rowIndex: number;
         field: string;
     }>;
+    /** 이 셀의 수식이 참조하는 선행 셀 목록. / Cells that this cell's formula references (its precedents).
+     *
+     * @param rowIndex - 대상 행의 flat index / Flat index of the target row
+     * @param field - 대상 컬럼 field / Target column field
+     * @returns 선행 셀들의 rowIndex/field 목록 / List of precedent cells' rowIndex/field
+     */
     getPrecedents(rowIndex: number, field: string): Array<{
         rowIndex: number;
         field: string;
     }>;
+    /** 그리드의 모든 수식을 강제 재계산한다. / Force-recalculate every formula in the grid. */
     recalculate(): void;
+    /** 단일 셀(과 그 의존 셀들)만 강제 재계산한다. / Force-recalculate a single cell (and its dependents).
+     *
+     * @param rowIndex - 대상 행의 flat index / Flat index of the target row
+     * @param field - 대상 컬럼 field / Target column field
+     */
     recalculateCell(rowIndex: number, field: string): void;
-    /** C3(F1 fill 전용): srcRowId/srcField 수식의 상대축만 dRow/dCol 오프셋한 새 수식 원문. */
+    /** C3(F1 fill 전용): srcRowId/srcField 수식의 상대축만 dRow/dCol 오프셋한 새 수식 원문.
+     * / C3 (F1 fill only): a new formula source with only the relative-axis references of the
+     * srcRowId/srcField formula offset by dRow/dCol.
+     *
+     * @param srcRowId - 원본 수식이 있는 행의 stable id / Stable id of the row holding the source formula
+     * @param srcField - 원본 수식이 있는 컬럼 field / Column field holding the source formula
+     * @param dRow - 행 오프셋 / Row offset
+     * @param dCol - 열 오프셋 / Column offset
+     * @returns 오프셋 적용된 수식 원문 / The offset formula source
+     */
     offsetFormula(srcRowId: string, srcField: string, dRow: number, dCol: number): string;
-    /** F3 렌더 배선(§4.4/C7, §7.4/§7.5/§7.6) — 셀 수식 메타(없으면 null). */
+    /** F3 렌더 배선(§4.4/C7, §7.4/§7.5/§7.6) — 셀 수식 메타(없으면 null).
+     * / F3 render wiring (§4.4/C7, §7.4/§7.5/§7.6) — a cell's formula metadata (or null if none).
+     *
+     * @param rowIndex - 대상 행의 flat index / Flat index of the target row
+     * @param field - 대상 컬럼 field / Target column field
+     * @returns 수식 원문/오류/근사 여부, 없으면 `null` / Formula source, error, and approximation flag; or `null`
+     */
     getFormulaMeta(rowIndex: number, field: string): {
         src: string;
         error: FormulaErrorCode | null;
         approx: boolean;
     } | null;
-    /** F3-R13/MCCONNELL-03(P0): 정렬/필터 후 범위-보유(hasRangeRef) 수식 전부 dirty(§3.5). */
+    /** F3-R13/MCCONNELL-03(P0): 정렬/필터 후 범위-보유(hasRangeRef) 수식 전부 dirty(§3.5).
+     * / F3-R13/MCCONNELL-03 (P0): after sort/filter, marks every range-referencing (hasRangeRef)
+     * formula dirty (§3.5). */
     recalcRangeBearingFormulas(): void;
 }