open-grid 1.1.1 → 1.2.1

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

@@ -7,13 +7,20 @@ import { CellRange } from '../types.js';
  * 폴백 렌더된다(CanvasAdapter._computeGeometry). 하위호환을 위해 타입 자체는 유지한다.
  */
 export type ChartType = 'bar' | 'line' | 'area' | 'pie' | 'doughnut' | 'bar-stacked' | 'bar-grouped';
+/** 시리즈(컬럼) 명세. / Series (column) spec. */
 export interface ChartSeriesSpec {
+    /** 값 컬럼 field 명. / Value column field name. */
     field: string;
+    /** 범례 라벨(기본 = 컬럼 header/field). / Legend label (default = column header/field). */
     name?: string;
+    /** 시리즈 색. / Series color. */
     color?: string;
+    /** 색 외 구분 패턴. / Non-color distinction pattern. */
     pattern?: ChartSeries['pattern'];
+    /** 시리즈별 렌더 타입(혼합 차트). / Per-series render type (mixed charts). */
     type?: 'bar' | 'line' | 'area';
 }
+/** 차트 데이터 소스(범위/선택/체크/전체/컬럼 지정). / Chart data source (range/selection/checked/all/explicit columns). */
 export type ChartSource = {
     kind: 'range';
     range?: CellRange;
@@ -28,61 +35,92 @@ export type ChartSource = {
     category?: string;
     series: Array<string | ChartSeriesSpec>;
 };
+/** 카테고리 집계 연산. / Category aggregation operation. */
 export type ChartAggregateOp = 'sum' | 'avg' | 'count' | 'min' | 'max';
+/** 집계 연산 또는 커스텀 리듀서. / An aggregation op or a custom reducer. */
 export type ChartAggregate = ChartAggregateOp | ((values: number[], category: string) => number);
+/** 접근성(SR) 테이블 모델 — 스크린리더 폴백. / Accessibility (SR) table model — screen-reader fallback. */
 export interface A11yTableModel {
-    /** aria-label 요약 캡션 */
+    /** aria-label 요약 캡션. / aria-label summary caption. */
     caption: string;
     /** ['category', ...series names] */
     colHeaders: string[];
-    /** [category, v1, v2, ...] — locale 포맷 문자열 */
+    /** [category, v1, v2, ...] — locale 포맷 문자열. / [category, v1, v2, ...] — locale-formatted strings. */
     rows: string[][];
 }
+/** 차트 시리즈(정규화된 값 배열). / Chart series (normalized value array). */
 export interface ChartSeries {
-    /** 범례 라벨(기본값 = 원본 컬럼 header/field) */
+    /** 범례 라벨(기본값 = 원본 컬럼 header/field). / Legend label (default = source column header/field). */
     name: string;
-    /** categories 와 동일 순서로 정렬. 결측=null */
+    /** categories 와 동일 순서로 정렬. 결측=null. / Aligned to categories order; missing = null. */
     data: Array<number | null>;
+    /** 시리즈 색. / Series color. */
     color?: string;
-    /** 색 외 구분(HANMS-19) */
+    /** 색 외 구분(HANMS-19). / Non-color distinction (HANMS-19). */
     pattern?: 'solid' | 'hatch' | 'dot' | 'cross';
 }
+/** 차트 데이터 모델 메타(출처·샘플링·집계 배지 정보). / Chart data model meta (source, sampling, aggregation badge info). */
 export interface ChartDataModelMeta {
+    /** 소스 종류. / Source kind. */
     sourceKind: ChartSource['kind'];
-    /** 원본 포인트(행) 수 */
+    /** 원본 포인트(행) 수. / Original point (row) count. */
     total: number;
-    /** LTTB 다운샘플 또는 category 집계로 축약됐는가 → 배지(§C) */
+    /** LTTB 다운샘플 또는 category 집계로 축약됐는가 → 배지(§C). / Whether reduced by LTTB downsample or category aggregation → badge (§C). */
     sampled: boolean;
+    /** 다운샘플 전 포인트 수. / Point count before downsampling. */
     sampledFrom?: number;
+    /** 다운샘플 후 포인트 수. / Point count after downsampling. */
     sampledTo?: number;
+    /** 적용된 집계 연산. / Applied aggregation op. */
     aggregatedOp?: 'sum' | 'avg' | 'count' | 'min' | 'max' | 'custom';
+    /** pie 에서 첫 시리즈만 사용됐는가. / Whether pie used only the first series. */
     pieReducedToFirst?: boolean;
+    /** pie 에서 음수를 절댓값 처리했는가. / Whether pie used absolute values for negatives. */
     negativesAbsInPie?: boolean;
-    /** SR 폴백 — extractor 가 렌더러와 무관하게 항상 채운다(§B 하드 게이트) */
+    /** SR 폴백 — extractor 가 렌더러와 무관하게 항상 채운다(§B 하드 게이트). / SR fallback — always filled by the extractor regardless of renderer (§B hard gate). */
     a11yTable: A11yTableModel;
 }
+/** 헤드리스 차트 데이터 모델(추출 산출물). / Headless chart data model (extraction output). */
 export interface ChartDataModel {
+    /** 카테고리(x축) 라벨. / Category (x-axis) labels. */
     categories: string[];
+    /** 시리즈 배열. / Series array. */
     series: ChartSeries[];
+    /** 모델 메타. / Model meta. */
     meta: ChartDataModelMeta;
 }
+/** 차트 테마(색·글꼴·팔레트). / Chart theme (colors, fonts, palette). */
 export interface ChartTheme {
+    /** 주 색. / Primary color. */
     primary: string;
+    /** 축·테두리 색. / Axis/border color. */
     border: string;
+    /** 텍스트 색. / Text color. */
     text: string;
+    /** 배경 색. / Background color. */
     bg: string;
+    /** 그리드 선 색. / Grid line color. */
     gridLine: string;
+    /** 글꼴 패밀리. / Font family. */
     fontFamily: string;
+    /** 기본 글꼴 크기(px). / Base font size in px. */
     fontSize: number;
+    /** 시리즈 순환 팔레트. / Series-cycling palette. */
     palette: string[];
 }
+/** 렌더 스펙(어댑터에 전달되는 스냅샷). / Render spec (snapshot passed to adapters). */
 export interface ChartRenderSpec {
+    /** 차트 타입. / Chart type. */
     type: ChartType;
+    /** 차트 제목. / Chart title. */
     title?: string;
+    /** 범례 표시/위치. / Legend visibility/position. */
     legend?: boolean | {
         position: 'top' | 'bottom' | 'left' | 'right';
     };
+    /** 툴팁 사용 여부. / Whether tooltips are enabled. */
     tooltip?: boolean;
+    /** 축 설정(라벨·min/max·스택). / Axis config (labels, min/max, stacked). */
     axis?: {
         xLabel?: string;
         yLabel?: string;
@@ -90,33 +128,56 @@ export interface ChartRenderSpec {
         yMax?: number;
         stacked?: boolean;
     };
+    /** 시리즈 팔레트(테마 팔레트 오버라이드). / Series palette (overrides theme palette). */
     palette?: string[];
+    /** 렌더 테마. / Render theme. */
     theme: ChartTheme;
+    /** 숫자 포맷터(축/툴팁/범례 컨텍스트). / Number formatter (axis/tooltip/legend context). */
     numberFormat?: (v: number, ctx: {
         axis: 'x' | 'y' | 'tooltip' | 'legend';
         field?: string;
     }) => string;
+    /** 접근성 테이블 모델. / Accessibility table model. */
     a11y: A11yTableModel;
 }
+/** 차트 포인트(히트테스트/클릭 대상). / Chart point (hit-test/click target). */
 export interface ChartPoint {
+    /** 시리즈 이름. / Series name. */
     seriesName: string;
+    /** 카테고리 라벨. / Category label. */
     category: string;
+    /** 값(결측 null). / Value (null if missing). */
     value: number | null;
+    /** 카테고리 인덱스. / Category index. */
     index: number;
+    /** 원본 행 stable id(있으면). / Source row stable id (if any). */
     rowId?: string;
 }
+/**
+ * 차트 렌더 어댑터(교체 seam) — 내장 canvas / 외부 lib 백엔드를 통일된 인터페이스로 감싼다.
+ * / Chart render adapter (swap seam) — wraps the built-in canvas / external-lib backends behind one interface.
+ */
 export interface ChartAdapter {
+    /** 어댑터 식별자. / Adapter identifier. */
     readonly id: string;
+    /** 호스트에 초기화. / Initialize into the host. */
     init(host: HTMLElement, spec: ChartRenderSpec): Promise<void>;
+    /** 모델을 렌더. / Render the model. */
     render(model: ChartDataModel, spec: ChartRenderSpec): void;
+    /** 렌더 영역 크기 변경. / Resize the render area. */
     resize(width: number, height: number): void;
+    /** 현재 렌더를 이미지 Blob 으로(선택). / Export current render as an image Blob (optional). */
     toBlob?(mime?: string): Promise<Blob | null>;
+    /** 포인트 클릭 콜백 등록(선택). / Register a point-click callback (optional). */
     onPointClick?(cb: (p: ChartPoint) => void): void;
+    /** 어댑터 정리. / Tear down the adapter. */
     destroy(): void;
 }
-/** createChart 반환 핸들(§6). 구현은 ChartManager. */
+/** createChart 반환 핸들(§6). 구현은 ChartManager. / Handle returned by createChart (§6); implemented by ChartManager. */
 export interface ChartInstance {
+    /** 차트 인스턴스 id. / Chart instance id. */
     readonly id: string;
+    /** 설정 패치 후 갱신. / Patch config and update. */
     update(patch?: Partial<ChartConfig>): void;
     /**
      * 모델을 재추출하고 렌더 스펙(테마 포함)을 재스냅샷해 재렌더한다(§5.3). 그리드는 테마 변경
@@ -124,56 +185,92 @@ export interface ChartInstance {
      * 변화 없는 순수 테마 전환 후에는, 열려 있는 각 차트에 대해 이 메서드를 호출해야 새 테마
      * (색·글꼴·팔레트)가 재적용된다. `update()`/`setType()`도 내부적으로 동일 경로를 탄다.
      */
+    /** 모델을 재추출하고 렌더 스펙(테마 포함)을 재스냅샷해 재렌더. / Re-extract the model and re-snapshot the render spec (incl. theme), then re-render. */
     refresh(): void;
+    /** 차트 타입 변경. / Change the chart type. */
     setType(type: ChartType): void;
+    /** 차트 인스턴스 파기. / Destroy the chart instance. */
     destroy(): void;
+    /** 현재 렌더를 이미지 Blob 으로. / Export current render as an image Blob. */
     toBlob(mime?: string): Promise<Blob | null>;
+    /** 현재 데이터 모델 반환. / Return the current data model. */
     getModel(): ChartDataModel;
+    /** 차트 이벤트 리스너 등록. / Register a chart event listener. */
     on(ev: 'chartRender' | 'chartPointClick', cb: (...a: any[]) => void): void;
 }
-/** GridOptions.chart 로 중첩되는 전역 옵션(C5.1, 최상위 flat 키 금지). */
+/** GridOptions.chart 로 중첩되는 전역 옵션(C5.1, 최상위 flat 키 금지). / Global options nested under GridOptions.chart (C5.1; no top-level flat keys). */
 export interface ChartGlobalOptions {
+    /** 차트 기능 활성화. / Enable the chart feature. */
     enabled?: boolean;
+    /** 기본 렌더 엔진. / Default render engine. */
     defaultEngine?: 'builtin' | 'chartjs' | 'echarts';
+    /** 기본 차트 타입. / Default chart type. */
     defaultType?: ChartType;
+    /** 기본 배치 방식. / Default placement. */
     placement?: 'docked' | 'modal' | 'inline' | 'floating';
+    /** 렌더 포인트 상한(초과 시 다운샘플). / Max render points (downsample above this). */
     maxPoints?: number;
+    /** live 갱신 디바운스(ms). / Debounce for live updates (ms). */
     debounceMs?: number;
+    /** 기본 팔레트. / Default palette. */
     palette?: string[];
+    /** 기본 숫자 포맷터. / Default number formatter. */
     numberFormat?: (v: number, ctx: {
         axis: 'x' | 'y' | 'tooltip' | 'legend';
         field?: string;
     }) => string;
+    /** 차트 생성 콜백. / Chart-create callback. */
     onChartCreate?: (i: ChartInstance) => void;
+    /** 차트 렌더 콜백. / Chart-render callback. */
     onChartRender?: (e: {
         id: string;
         model: ChartDataModel;
     }) => void;
+    /** 포인트 클릭 콜백. / Point-click callback. */
     onChartPointClick?: (e: {
         id: string;
         point: ChartPoint;
     }) => void;
+    /** 차트 파기 콜백. / Chart-destroy callback. */
     onChartDestroy?: (e: {
         id: string;
     }) => void;
 }
+/** createChart() 공개 설정(§6). / Public config for createChart() (§6). */
 export interface ChartConfig {
+    /** 데이터 소스. / Data source. */
     source: ChartSource;
+    /** 차트 타입. / Chart type. */
     type: ChartType;
+    /** 렌더 엔진 또는 커스텀 어댑터. / Render engine or custom adapter. */
     engine?: 'builtin' | 'chartjs' | 'echarts' | ChartAdapter;
+    /** 배치 방식. / Placement. */
     placement?: 'docked' | 'modal' | 'inline' | 'floating';
+    /** inline/floating 시 마운트 대상. / Mount target for inline/floating. */
     mount?: HTMLElement;
+    /** 카테고리(x축) 컬럼 field. / Category (x-axis) column field. */
     category?: string;
+    /** 시리즈 명세 목록. / Series specs. */
     series?: Array<string | ChartSeriesSpec>;
+    /** 카테고리 집계 연산. / Category aggregation op. */
     aggregate?: ChartAggregate;
+    /** 렌더 포인트 상한. / Max render points. */
     maxPoints?: number;
+    /** 데이터 변경 시 자동 갱신. / Auto-refresh on data changes. */
     live?: boolean;
+    /** 차트 제목. / Chart title. */
     title?: string;
+    /** 범례 설정. / Legend config. */
     legend?: ChartRenderSpec['legend'];
+    /** 툴팁 사용 여부. / Whether tooltips are enabled. */
     tooltip?: boolean;
+    /** 축 설정. / Axis config. */
     axis?: ChartRenderSpec['axis'];
+    /** 시리즈 팔레트. / Series palette. */
     palette?: string[];
+    /** 숫자 포맷터. / Number formatter. */
     numberFormat?: ChartRenderSpec['numberFormat'];
+    /** 렌더 크기(px). / Render size (px). */
     size?: {
         width: number;
         height: number;

package/dist/types/core/detail/DetailGlyph.d.ts

@@ -12,6 +12,8 @@
  * 렌더 배선(GridRenderer expander 셀)이 이 모듈의 순수 함수/상수를 소비해 실제 DOM 속성을 채운다.
  * 이 파일은 DOM 을 만들지 않는다 — 문자열/속성 값만 생성.
  */
+/** i18n: 글리프 aria/툴팁 로케일 해석기(주입 없으면 전역 t). / i18n: glyph aria/tooltip resolver (global t when not injected). */
+export type DetailGlyphT = (key: string, params?: Record<string, string | number>) => string;
 /** 트리 셰브론(▸/▾)과 충돌하지 않는 전용 글리프(C10 기본값). */
 export declare const DETAIL_GLYPH_COLLAPSED = "\u2295";
 export declare const DETAIL_GLYPH_EXPANDED = "\u2296";
@@ -32,7 +34,7 @@ export interface DetailGlyphInfo {
  * 펼침 여부에 따른 글리프/aria-label/title 조합을 반환한다. 트리 셰브론과 절대 겹치지 않는
  * 문자셋만 사용(C10 R-DETAIL-GLYPH 하드 룰).
  */
-export declare function getDetailGlyph(expanded: boolean): DetailGlyphInfo;
+export declare function getDetailGlyph(expanded: boolean, t?: DetailGlyphT): DetailGlyphInfo;
 /** NFR-5(1): 마스터 행 `aria-expanded` 값(문자열 — DOM setAttribute 그대로 사용). */
 export declare function getMasterRowAriaExpanded(expanded: boolean): 'true' | 'false';
 /**

package/dist/types/core/editors/CellEditor.d.ts

@@ -2,16 +2,25 @@ import { ColumnDef, EditorDef } from '../types.js';
 import { RenderContext } from '../renderers/CellRenderer.js';
 export { DateEditor } from './DateEditor.js';
 export { SelectEditor } from './SelectEditor.js';
+/** 편집 결과(커밋 여부 + 값). / Edit result (whether committed + value). */
 export interface EditorResult {
+    /** 커밋(확정) 여부. / Whether committed. */
     committed: boolean;
+    /** 편집된 값. / Edited value. */
     value: any;
 }
+/** 셀 에디터 인터페이스 — 편집 위젯 수명 관리. / Cell editor interface — manages the edit widget lifecycle. */
 export interface CellEditor {
+    /** 컨테이너에 편집 위젯을 마운트한다. / Mount the edit widget into the container. */
     mount(container: HTMLElement, ctx: RenderContext, onCommit: (value: any) => void, onCancel: () => void): void;
+    /** 현재 편집 값을 반환한다. / Return the current edit value. */
     getValue(): any;
+    /** 편집 위젯에 포커스한다. / Focus the edit widget. */
     focus(): void;
+    /** 편집 위젯을 정리한다. / Tear down the edit widget. */
     destroy(): void;
 }
+/** 텍스트 입력 에디터. / Text input editor. */
 export declare class TextEditor implements CellEditor {
     private input;
     private _onCommit;
@@ -23,6 +32,7 @@ export declare class TextEditor implements CellEditor {
     focus(): void;
     destroy(): void;
 }
+/** 숫자 입력 에디터(min/max/step 지원). / Number input editor (supports min/max/step). */
 export declare class NumberEditor implements CellEditor {
     private input;
     private _onCommit;
@@ -43,6 +53,7 @@ export declare class NumberEditor implements CellEditor {
     focus(): void;
     destroy(): void;
 }
+/** 체크박스 에디터(change 즉시 커밋). / Checkbox editor (commits immediately on change). */
 export declare class CheckboxEditor implements CellEditor {
     private chk;
     private _onCommit;
@@ -62,9 +73,25 @@ export declare class CheckboxEditor implements CellEditor {
  *  - number 는 def 가 있으면 min/max/step 을 옵션으로, 없으면 기본 NumberEditor.
  *  - select 는 def 가 있으면 def.options, 없으면 col.options 를 쓴다(원 switch 와 동일).
  */
+/** 셀 에디터 팩토리 시그니처 `(col, def?) => CellEditor`. / Cell-editor factory signature `(col, def?) => CellEditor`. */
 export type EditorFactory = (col: ColumnDef, def?: EditorDef) => CellEditor;
-/** 커스텀 셀 에디터 타입을 코어 편집 없이 등록(OCP). 프로세스 전역. */
+/**
+ * 커스텀 셀 에디터 타입을 코어 편집 없이 등록(OCP). 프로세스 전역.
+ * / Register a custom cell-editor type without editing core (OCP). Process-global.
+ *
+ * @param typeName - 에디터 타입 이름(예: 'color') / Editor type name (e.g. 'color')
+ * @param factory - 에디터 팩토리 / Editor factory
+ * @example
+ * registerEditor('color', () => new TextEditor());
+ */
 export declare function registerEditor(typeName: string, factory: EditorFactory): void;
-/** 등록 여부 조회(내부/테스트용). */
+/** 에디터 타입 등록 여부 조회(내부/테스트용). / Whether an editor type is registered (internal/test use). */
 export declare function hasEditor(typeName: string): boolean;
+/**
+ * 컬럼 정의로부터 셀 에디터를 생성한다(레지스트리 해석, 미등록 시 TextEditor 폴백).
+ * / Create a cell editor from a column definition (registry resolution; falls back to TextEditor when unregistered).
+ *
+ * @param col - 컬럼 정의 / Column definition
+ * @returns 셀 에디터 / A cell editor
+ */
 export declare function createEditor(col: ColumnDef): CellEditor;

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

@@ -1,48 +1,100 @@
 import { OGDecimal } from '../OGDecimal.js';
+/** 셀 키 문자열 `${rowId}:${field}`(내부 전용 포맷). / Cell key string `${rowId}:${field}` (internal format). */
 export type CellKey = string;
+/**
+ * rowId·field 로 셀 키를 만든다. / Build a cell key from rowId and field.
+ *
+ * @param rowId - 행 stable id / Row stable id
+ * @param field - 컬럼 field 명 / Column field name
+ * @returns `${rowId}:${field}` 형태의 키 / A `${rowId}:${field}` key
+ */
 export declare function cellKey(rowId: string, field: string): CellKey;
+/**
+ * 셀 키를 rowId·field 로 분해한다. / Split a cell key back into rowId and field.
+ *
+ * @param key - 셀 키 문자열 / Cell key string
+ * @returns { rowId, field }
+ */
 export declare function parseCellKey(key: CellKey): {
     rowId: string;
     field: string;
 };
+/**
+ * 수식 에러 코드. / Formula error code.
+ *
+ * `#ERR`(일반), `#REF`(참조 무효), `#CYCLE`(순환), `#DIV0`(0 나눗셈), `#NAME`(미정의 이름),
+ * `#VALUE`(비수치), `#NUM`(수치 범위).
+ * / `#ERR` (general), `#REF` (invalid ref), `#CYCLE` (cyclic), `#DIV0` (divide by zero),
+ * `#NAME` (undefined name), `#VALUE` (non-numeric), `#NUM` (numeric range).
+ */
 export type FormulaErrorCode = '#ERR' | '#REF' | '#CYCLE' | '#DIV0' | '#NAME' | '#VALUE' | '#NUM';
+/** 전체 에러 코드 집합(런타임 판별용). / Set of all error codes (for runtime checks). */
 export declare const FORMULA_ERROR_CODES: ReadonlySet<string>;
-/** 값이 이미 다른 수식의 에러 결과(문자열)인지 판별 — 에러 전파(§6 EVANS/DEMARCO 규칙)용. */
+/**
+ * 값이 이미 다른 수식의 에러 결과(문자열)인지 판별 — 에러 전파용. / Detect whether a value is already another formula's error result (string) — for error propagation.
+ *
+ * @param v - 검사할 값 / Value to inspect
+ * @returns 에러 코드 또는 null / The error code, or null
+ */
 export declare function isErrorToken(v: unknown): FormulaErrorCode | null;
+/** 수식 셀의 계산 결과 값 타입. / Computed result value type of a formula cell. */
 export type CellValue = OGDecimal | string | boolean | null;
+/** 참조 정규화 모드: 'stable'(rowId 앵커) | 'relative'(행 오프셋). / Reference normalization mode: 'stable' (rowId anchor) | 'relative' (row offset). */
 export type RefMode = 'stable' | 'relative';
+/** 정규화된 절대 참조(rowId 앵커). / Normalized absolute reference (rowId anchor). */
 export interface CanonicalAbsRef {
     kind: 'abs';
+    /** 앵커 행 stable id. / Anchor row stable id. */
     rowId: string;
+    /** 컬럼 field 명. / Column field name. */
     field: string;
+    /** 원문에 '$' 행 고정이 있었는지. / Whether the source had a '$' row lock. */
     dollarRow: boolean;
+    /** 원문에 '$' 열 고정이 있었는지. / Whether the source had a '$' column lock. */
     dollarCol: boolean;
 }
+/** 정규화된 상대 참조(행 오프셋). / Normalized relative reference (row offset). */
 export interface CanonicalRelRef {
     kind: 'rel';
+    /** 현재 셀 기준 행 오프셋 (refMode:'relative' 전용, §2.3). / Row offset from the current cell (refMode:'relative' only, §2.3). */
     dRow: number;
+    /** 컬럼 field 명. / Column field name. */
     field: string;
+    /** rel 인데 dollarRow=true 인 경우는 없음(구조상 dollarRow=true 면 abs). / Never true for rel (a '$' row lock structurally implies abs). */
     dollarRow: boolean;
+    /** 열 고정 여부. / Whether the column is locked. */
     dollarCol: boolean;
 }
+/** 정규화된 단일 참조(절대 | 상대). / Normalized single reference (absolute | relative). */
 export type CanonicalRef = CanonicalAbsRef | CanonicalRelRef;
+/** 정규화된 범위 참조(두 코너). / Normalized range reference (two corners). */
 export interface CanonicalRangeRef {
+    /** 코너1 (원문 좌측/상단 그대로, 정렬은 evaluate-time §3.5). / Corner 1 (kept as source left/top; ordering happens at evaluate-time §3.5). */
     a: CanonicalRef;
+    /** 코너2. / Corner 2. */
     b: CanonicalRef;
 }
+/** 파서 원시 셀 참조 노드(정규화 전). / Raw parser cell-reference node (pre-normalization). */
 export interface RawCellRefNode {
     t: 'rawRef';
+    /** A1 열문자. / A1 column letters. */
     colLetters: string;
+    /** 1-based 행 번호. / 1-based row number. */
     row: number;
+    /** 열 '$' 고정. / Column '$' lock. */
     dollarCol: boolean;
+    /** 행 '$' 고정. / Row '$' lock. */
     dollarRow: boolean;
 }
+/** 파서 원시 범위 참조 노드(정규화 전). / Raw parser range-reference node (pre-normalization). */
 export interface RawRangeRefNode {
     t: 'rawRange';
     a: RawCellRefNode;
     b: RawCellRefNode;
 }
+/** 수식 이항 연산자. / Formula binary operator. */
 export type BinOp = '+' | '-' | '*' | '/' | '%' | '^' | '&' | '=' | '<>' | '<' | '<=' | '>' | '>=';
+/** 수식 AST 노드(원시 참조 + 정규화 후 노드 공존 유니온). / Formula AST node (union of raw refs and normalized nodes). */
 export type AstNode = {
     t: 'num';
     v: string;
@@ -78,27 +130,38 @@ export type AstNode = {
     left: AstNode;
     right: AstNode;
 };
+/** 수식 셀 사이드카 저장 단위(§3.4/§4.1). / Formula-cell sidecar storage unit (§3.4/§4.1). */
 export interface FormulaCell {
+    /** 원문 "=A1+B2"(편집 표시용, §4.3). / Source text "=A1+B2" (for edit display, §4.3). */
     src: string;
+    /** 정규화된 AST. / Normalized AST. */
     ast: AstNode;
+    /** 범위 참조 포함 여부 → applySort/applyFilter dirty 대상(§3.5 P0). / Whether a range ref is present → dirtied by applySort/applyFilter (§3.5 P0). */
     hasRangeRef: boolean;
+    /** 캐시된 계산 결과. / Cached computed result. */
     value: CellValue;
+    /** 에러 코드(없으면 null). / Error code (null if none). */
     error: FormulaErrorCode | null;
+    /** 근사(SQRT 등) 포함 여부 → ≈ 표식(C11). / Whether approximation (e.g. SQRT) is involved → ≈ marker (C11). */
     approx?: boolean;
 }
+/**
+ * 수식 엔진이 그리드/데이터를 보는 유일한 인터페이스(주입, 의존성 역전 C0/C0.3/C1).
+ * / The sole interface through which the formula engine views the grid/data (injected, dependency inversion C0/C0.3/C1).
+ */
 export interface FormulaGridAccessor {
-    /** A1 열문자 매핑 기준 — visibleLeaves(숨김 제외) 순서의 field 배열(§3.1/C1). */
+    /** A1 열문자 매핑 기준 — visibleLeaves(숨김 제외) 순서의 field 배열(§3.1/C1). / A1 column-letter basis — field array in visibleLeaves order (hidden excluded) (§3.1/C1). */
     visibleFields(): string[];
-    /** flat index(0-based) → rowId. kind!=='data' 이거나 범위 밖이면 null(§C0.3). */
+    /** flat index(0-based) → rowId. kind!=='data' 이거나 범위 밖이면 null(§C0.3). / flat index (0-based) → rowId; null when kind!=='data' or out of range (§C0.3). */
     rowIdAtFlat(flatIndex: number): string | null;
-    /** rowId → 현재 flat index(0-based). 없음/필터아웃/접힘이면 -1. */
+    /** rowId → 현재 flat index(0-based). 없음/필터아웃/접힘이면 -1. / rowId → current flat index (0-based); -1 when absent/filtered-out/collapsed. */
     flatIndexOfRowId(rowId: string): number;
-    /** 현재 표시(필터 통과) 순서의 rowId 배열 — 범위 evaluate-time 멤버십 해소용(§3.5). */
+    /** 현재 표시(필터 통과) 순서의 rowId 배열 — 범위 evaluate-time 멤버십 해소용(§3.5). / rowId array in current display (filtered) order — for evaluate-time range membership (§3.5). */
     displayedRowIds(): string[];
-    /** (rowId, field) 셀의 원시 값(비수식, 이미 계산된 값 포함) 조회. */
+    /** (rowId, field) 셀의 원시 값(비수식, 이미 계산된 값 포함) 조회. / Read the raw value at (rowId, field) (non-formula; includes already-computed values). */
     getCellValue(rowId: string, field: string): unknown;
-    /** rowId 존재 여부(행 삭제 감지, F3-R28). */
+    /** rowId 존재 여부(행 삭제 감지, F3-R28). / Whether a rowId exists (row-deletion detection, F3-R28). */
     hasRow(rowId: string): boolean;
-    /** field 존재 여부(열 삭제 감지, F3-R28). */
+    /** field 존재 여부(열 삭제 감지, F3-R28). / Whether a field exists (column-deletion detection, F3-R28). */
     hasField(field: string): boolean;
 }

package/dist/types/core/i18n/interpolate.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `{name}` 명명 파라미터를 치환한다. `{{`→`{`, `}}`→`}` 이스케이프. 누락 파라미터는 플레이스홀더 유지.
+ * / Substitute `{name}` params. Escapes `{{`→`{`, `}}`→`}`. Missing params keep the placeholder.
+ */
+export declare function interpolate(template: string, params?: Readonly<Record<string, string | number>>): string;