open-grid 1.0.8 → 1.1.0

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

@@ -0,0 +1,6 @@
+import { AstNode, FormulaGridAccessor } from './types.js';
+/** 정규화 AST를 다시 "=..." 형태의 A1 원문으로 직렬화한다(offsetFormula 결과물 조립용). */
+export declare function astToSource(ast: AstNode, host: {
+    rowId: string;
+    field: string;
+}, accessor: FormulaGridAccessor): string;

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

@@ -0,0 +1,104 @@
+import { OGDecimal } from '../OGDecimal.js';
+export type CellKey = string;
+export declare function cellKey(rowId: string, field: string): CellKey;
+export declare function parseCellKey(key: CellKey): {
+    rowId: string;
+    field: string;
+};
+export type FormulaErrorCode = '#ERR' | '#REF' | '#CYCLE' | '#DIV0' | '#NAME' | '#VALUE' | '#NUM';
+export declare const FORMULA_ERROR_CODES: ReadonlySet<string>;
+/** 값이 이미 다른 수식의 에러 결과(문자열)인지 판별 — 에러 전파(§6 EVANS/DEMARCO 규칙)용. */
+export declare function isErrorToken(v: unknown): FormulaErrorCode | null;
+export type CellValue = OGDecimal | string | boolean | null;
+export type RefMode = 'stable' | 'relative';
+export interface CanonicalAbsRef {
+    kind: 'abs';
+    rowId: string;
+    field: string;
+    dollarRow: boolean;
+    dollarCol: boolean;
+}
+export interface CanonicalRelRef {
+    kind: 'rel';
+    dRow: number;
+    field: string;
+    dollarRow: boolean;
+    dollarCol: boolean;
+}
+export type CanonicalRef = CanonicalAbsRef | CanonicalRelRef;
+export interface CanonicalRangeRef {
+    a: CanonicalRef;
+    b: CanonicalRef;
+}
+export interface RawCellRefNode {
+    t: 'rawRef';
+    colLetters: string;
+    row: number;
+    dollarCol: boolean;
+    dollarRow: boolean;
+}
+export interface RawRangeRefNode {
+    t: 'rawRange';
+    a: RawCellRefNode;
+    b: RawCellRefNode;
+}
+export type BinOp = '+' | '-' | '*' | '/' | '%' | '^' | '&' | '=' | '<>' | '<' | '<=' | '>' | '>=';
+export type AstNode = {
+    t: 'num';
+    v: string;
+} | {
+    t: 'str';
+    v: string;
+} | {
+    t: 'bool';
+    v: boolean;
+} | {
+    t: 'field';
+    field: string;
+} | RawCellRefNode | RawRangeRefNode | {
+    t: 'ref';
+    ref: CanonicalRef;
+} | {
+    t: 'range';
+    ref: CanonicalRangeRef;
+} | {
+    t: 'error';
+    code: FormulaErrorCode;
+} | {
+    t: 'call';
+    name: string;
+    args: AstNode[];
+} | {
+    t: 'unary';
+    op: '+' | '-';
+    arg: AstNode;
+} | {
+    t: 'bin';
+    op: BinOp;
+    left: AstNode;
+    right: AstNode;
+};
+export interface FormulaCell {
+    src: string;
+    ast: AstNode;
+    hasRangeRef: boolean;
+    value: CellValue;
+    error: FormulaErrorCode | null;
+    approx?: boolean;
+}
+export interface FormulaGridAccessor {
+    /** A1 열문자 매핑 기준 — visibleLeaves(숨김 제외) 순서의 field 배열(§3.1/C1). */
+    visibleFields(): string[];
+    /** flat index(0-based) → rowId. kind!=='data' 이거나 범위 밖이면 null(§C0.3). */
+    rowIdAtFlat(flatIndex: number): string | null;
+    /** rowId → 현재 flat index(0-based). 없음/필터아웃/접힘이면 -1. */
+    flatIndexOfRowId(rowId: string): number;
+    /** 현재 표시(필터 통과) 순서의 rowId 배열 — 범위 evaluate-time 멤버십 해소용(§3.5). */
+    displayedRowIds(): string[];
+    /** (rowId, field) 셀의 원시 값(비수식, 이미 계산된 값 포함) 조회. */
+    getCellValue(rowId: string, field: string): unknown;
+    /** rowId 존재 여부(행 삭제 감지, F3-R28). */
+    hasRow(rowId: string): boolean;
+    /** field 존재 여부(열 삭제 감지, F3-R28). */
+    hasField(field: string): boolean;
+}

package/dist/types/core/range/ClipboardCodec.d.ts

@@ -0,0 +1,30 @@
+import { CellRange, FlatRowRefLike } from './types.js';
+export interface ClipboardQueryContext {
+    fieldAt(ci: number): string | undefined;
+    getCellValue(ri: number, field: string): any;
+    /** override 데모 정합: 있으면 표시값 우선(§5.1 주석) */
+    getDisplayText?(ri: number, field: string): string;
+}
+/** R행×C열 범위 → TSV(행마다 \t조인, 행간 \n) — 엑셀 왕복 호환(UR-4 AC). */
+export declare function rangeToTSV(rect: CellRange, ctx: ClipboardQueryContext): string;
+/** TSV 문자열 → 2D 블록(행×열 문자열 배열). 빈 문자열은 1×1 빈 블록. */
+export declare function parseTSV(text: string): string[][];
+export interface PastePlanContext {
+    resolveFlatRow(ri: number): FlatRowRefLike;
+    fieldAt(ci: number): string | undefined;
+    /** 기본 true(잠금 없음) */
+    isEditable?(rowId: string, field: string): boolean;
+}
+export interface PastePlanItem {
+    rowIndex: number;
+    field: string;
+    action: 'value' | 'skip';
+    value?: any;
+    reason?: string;
+}
+/**
+ * 붙여넣기 소스 블록(2D) + 타깃 range → 플랜.
+ * 소스가 타깃보다 작으면 타일 반복, 크면(또는 같으면) 블록 그대로 전개(타깃 크기 무시) — 엑셀 규칙(FR-4 AC).
+ * `r % blockRows`/`c % blockCols` 단일 공식으로 두 경우 모두 성립(작을 때=주기 반복, 클 때=outRows=blockRows라 항상 r 자신).
+ */
+export declare function buildPastePlan(block: string[][], target: CellRange, ctx: PastePlanContext): PastePlanItem[];

package/dist/types/core/range/FillEngine.d.ts

@@ -0,0 +1,63 @@
+import { OGDecimal } from '../OGDecimal.js';
+import { CellRange, FillAxis, FillMode, FlatRowRefLike } from './types.js';
+export interface DetectSeriesResult {
+    kind: 'copy' | 'arith' | 'text-suffix';
+    /** 자연순서(위→아래 / 왼→오) diff. arith/text-suffix에만 존재 */
+    step?: OGDecimal;
+    /** 자연순서로 파싱된 수치값(arith) 또는 접미 숫자부(text-suffix) */
+    values?: OGDecimal[];
+    /** text-suffix의 공통 접두문자열 */
+    prefix?: string;
+}
+/**
+ * 소스 라인(주축과 직교하는 한 행 또는 한 열의 값 배열, 자연순서=위→아래/왼→오) → 감지 결과.
+ * 경계 AC(REQ-24): [1,2,4]→copy, [5]→copy, ["a","b"]→copy, ["Q1","Q2"]→arith 아님 text-suffix(step=1).
+ */
+export declare function detectSeries(sourceLine: any[]): DetectSeriesResult;
+/**
+ * 감지 결과 + 자연순서 소스라인으로 target 거리 d(1..N, 소스에 가장 가까운 셀=1)의 값을 외삽.
+ * 방향 부호(§3.4.1 "위/왼쪽 채우면 step 부호 반전")는 axis에 따라 base/부호를 선택해 처리한다.
+ */
+export declare function extrapolateValue(result: DetectSeriesResult, sourceLine: any[], axis: FillAxis, d: number): any;
+export interface FillPlanItem {
+    rowIndex: number;
+    field: string;
+    action: 'value' | 'setFormula' | 'skip';
+    value?: any;
+    formula?: string;
+    reason?: string;
+}
+export interface FillPlanResult {
+    items: FillPlanItem[];
+    /** C3.2 보존된 수식 셀 수(announce용) */
+    skippedFormula: number;
+}
+export interface FillPlanContext {
+    resolveFlatRow(ri: number): FlatRowRefLike;
+    fieldAt(ci: number): string | undefined;
+    getCellValue(ri: number, field: string): any;
+    /** 기본 true(잠금 없음) */
+    isEditable?(rowId: string, field: string): boolean;
+    /** 기본 false(수식 없음) */
+    hasCellFormula?(rowId: string, field: string): boolean;
+    /** C3.1: 상대 ref 오프셋 수식 생성(F3 제공) */
+    offsetFormula?(rowId: string, field: string, dRow: number, dCol: number): string;
+    /** rangeSelection.fillOverwriteFormula(C3.2 opt-in) */
+    overwriteFormula?: boolean;
+    /** Ctrl-강제-copy: 수식 원문 복제(오프셋 없음) */
+    forceCopyFormula?: boolean;
+}
+/**
+ * 소스 rect → 타깃 rect 채우기 플랜(§3.5). 주축과 직교하는 각 라인(행 또는 열) 별로 독립 처리(§3.4.1).
+ * non-data 행(kind!=='data')은 항상 skip(C0.3/CON-5). mode==='series'가 detectSeries로 'copy'에
+ * 귀결되면(경계 케이스) 그대로 copy 타일 반복으로 처리된다(설계가 의도한 동작).
+ */
+export declare function buildFillPlan(source: CellRange, target: CellRange, axis: FillAxis, mode: FillMode, ctx: FillPlanContext): FillPlanResult;
+/**
+ * 현재 선택 rect에서 Ctrl+D(아래로)/Ctrl+R(오른쪽으로) 채우기의 source/target rect 산출(순수 함수).
+ * 1행(D)/1열(R)뿐이면 채울 대상이 없어 null.
+ */
+export declare function ctrlFillSourceTarget(rect: CellRange, axis: 'down' | 'right'): {
+    source: CellRange;
+    target: CellRange;
+} | null;

package/dist/types/core/range/RangeModel.d.ts

@@ -0,0 +1,53 @@
+import { CellCoord, CellRange, Direction, RangeIdentity, RangeModelHost } from './types.js';
+/** anchor/focus → 정규화된 CellRange(§2.3). 역방향 드래그(anchor>focus)도 min/max로 정규화. */
+export declare function normalize(a: CellCoord, f: CellCoord): CellRange;
+export declare class RangeModel {
+    private _host;
+    private _anchor;
+    private _focus;
+    private _identity;
+    private _rects;
+    private _hasSelection;
+    private _additive;
+    constructor(host: RangeModelHost);
+    get hasSelection(): boolean;
+    getAnchor(): CellCoord;
+    getFocus(): CellCoord;
+    getIdentity(): RangeIdentity;
+    /** 공개 API 재료(C4): 정규화 rects (없으면 []). MVP는 길이 ≤1. */
+    getRangeSelection(): CellRange[];
+    /** 공개 API 재료(C4): getRangeSelection()[0] ?? null */
+    getActiveRange(): CellRange | null;
+    /** 복사/채우기 소스 결정용 별칭(§5.1 getPrimaryRect) */
+    getPrimaryRect(): CellRange | null;
+    /** 정렬/필터 후에도 유지되는 실제 rowId 집합의 현재 flat 위치(오름차순, 화면밖=-1 제외). */
+    getProjectedFlatRows(): number[];
+    /** pointerdown. shift=true면 기존 anchor 유지(있을 때만), 아니면 새 1x1 anchor. */
+    beginDrag(ri: number, ci: number, opts?: {
+        additive?: boolean;
+        shift?: boolean;
+    }): void;
+    /** pointermove. */
+    updateFocus(ri: number, ci: number): void;
+    /** pointerup — 확정 + 정체성 스냅샷(§2.5). */
+    endDrag(): void;
+    get additive(): boolean;
+    /** 클릭(비-Shift): 새 1×1 anchor(FR-1). */
+    click(ri: number, ci: number): void;
+    /** Shift+클릭: anchor 유지, focus만 갱신. anchor 없으면 click으로 위임(UC-2 예외). */
+    shiftClickExtend(ri: number, ci: number): void;
+    /** anchor 고정, focus만 1칸 이동(격자 경계 clamp). 편집 우선순위(C9)는 호출측(KeyboardManager)이 가드. */
+    extendFocus(dir: Direction): void;
+    setRect(rect: CellRange): void;
+    /** clearRangeSelection API 재료. */
+    clear(): void;
+    /** 현재 rect를 rowId 집합 × field 집합으로 스냅샷(display-index는 렌더용 투영일 뿐). */
+    snapshotIdentity(): void;
+    /**
+     * 정렬/필터 후 호출(onModelReproject 구독 지점). rowId 집합 → 현재 flat 좌표로 재투영.
+     * 사라진 행(flatIndexOfRowId === -1)은 정체성에는 남되 투영(rects)에서는 제외된다(불연속 허용).
+     * MVP는 단일 bounding rect로 투영(§2.2 rects 길이 1 방침) — 남아있는 행들의 min/max로 계산.
+     */
+    reproject(): void;
+    private _recompute;
+}

package/dist/types/core/range/RangeQuery.d.ts

@@ -0,0 +1,16 @@
+import { CellRange } from './types.js';
+export interface RangeQueryContext {
+    fieldAt(ci: number): string | undefined;
+    getCellValue(ri: number, field: string): any;
+}
+/** rect 값 2D 배열(FR-6). */
+export declare function getRangeValues(rect: CellRange, ctx: RangeQueryContext): any[][];
+export interface RangeStats {
+    sum: string;
+    avg: string;
+    count: number;
+    min: string;
+    max: string;
+}
+/** 숫자 셀에 대해 OGDecimal 기반 sum/avg/count/min/max(FR-6). 숫자 셀이 없으면 null. */
+export declare function getRangeStats(rect: CellRange, ctx: RangeQueryContext): RangeStats | null;

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

@@ -0,0 +1,47 @@
+import { CellRange } from '../types.js';
+export type { CellRange };
+/** 방향성 원시 좌표. ri=flat/visual index(C0.2), ci=visibleLeaves index(C0.4). */
+export interface CellCoord {
+    ri: number;
+    ci: number;
+}
+export type Direction = 'up' | 'down' | 'left' | 'right';
+export type FillAxis = Direction;
+export type FillMode = 'copy' | 'series';
+/** 범위 정체성(C0.5) — display-index가 아니라 stable 집합으로 저장. */
+export interface RangeIdentity {
+    /** 선택된 data 행의 stable _ogRowId 집합 (정렬/필터를 넘어 보존) */
+    rowIds: string[];
+    /** 선택된 열의 field 집합 (visibleLeaves.field) */
+    fields: string[];
+}
+/** FlatRowModel.resolveFlatRow가 반환하는 참조(C0.3). */
+export interface FlatRowRefLike {
+    kind: 'data' | 'group' | 'tree' | 'detailHead' | 'detailFiller';
+    rowId?: string;
+    dataIndex?: number;
+    displayIndex?: number;
+}
+/**
+ * F1이 좌표 해소·재투영을 위해 필요로 하는 최소 계약 모양(C0.3 FlatRowModel + visibleLeaves).
+ * 실제 구현(baseline FlatRowModel/ColumnLayout)은 이 형태를 만족하는 어댑터를 배선 단계에서 주입한다.
+ */
+export interface RangeModelHost {
+    /** flat/visual 행 총수 */
+    count(): number;
+    /** flat index → 참조(kind/rowId 등). 없으면 kind 판별 불가 상태를 반환해야 함(C0.3) */
+    resolveFlatRow(flatIndex: number): FlatRowRefLike;
+    /** stable rowId → 현재 flat index. 없으면(접힘/필터아웃) -1 */
+    flatIndexOfRowId(rowId: string): number;
+    /** flat index → stable rowId (data/tree만, 그 외 null) */
+    rowIdOfFlat(flatIndex: number): string | null;
+    /** 현재 visibleLeaves의 field 목록(순서=ci) */
+    visibleFields(): string[];
+}
+/** 채우기 프리뷰(핸들 드래그 중) — 커밋 전 임시 상태 자료(§2.2 FillPreview). */
+export interface FillPreview {
+    source: CellRange;
+    target: CellRange;
+    axis: FillAxis;
+    mode: FillMode;
+}

package/dist/types/core/renderers/CellRenderer.d.ts

@@ -8,6 +8,8 @@ export interface RenderContext<T = any> {
     isSelected: boolean;
     rowState: 'none' | 'added' | 'edited' | 'removed';
     displayValue?: string | null;
+    /** C7(15_cross_contracts.md/F3-R14): 이 셀에 F3 셀 수식이 있으면 true — ColumnDef.formula 재평가를 skip. */
+    hasCellFormula?: boolean;
 }
 export interface CellRenderer {
     render(ctx: RenderContext): HTMLElement;

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

@@ -1,3 +1,5 @@
+import { FormulaErrorCode } from './formula/types.js';
+import { RangeStats as _RangeStats } from './range/RangeQuery.js';
 export type DataType = 'string' | 'number' | 'date' | 'boolean' | 'select' | 'radio' | 'img' | 'html' | 'barcode';
 export type { MaskType, MaskDef } from './MaskingEngine.js';
 export type SelectionMode = 'single' | 'row' | 'multiple' | 'cells';
@@ -103,12 +105,144 @@ export interface SelectionEvent<T = any> {
     rowIndexes: number[];
     cells?: CellRange[];
 }
+/**
+ * CellRangeSemantics — CellRange 의미 규범(C0.4, 15_cross_contracts.md). 소유자 = F1(범위 선택).
+ * F3(수식 ref)·F4(차트 소스)는 이 의미로만 CellRange 를 소비한다.
+ *  - startRow/endRow : flat/visual index (C0.2 — FlatRowModel 이 다루는 화면 표시 순서).
+ *    group/tree pseudo-row, (F2 도입 후) detail head/filler 도 포함한 인덱스 공간이며,
+ *    display index(정렬/필터만 반영, group/tree 제외)와 다르다.
+ *  - startCol/endCol : `ColumnLayout.visibleLeaves` 인덱스(숨김 컬럼 제외). 숨김 컬럼은
+ *    좌표를 흔들지 않되, 언하이드 시 재렌더로 좌표 표시(A1 등)가 갱신된다.
+ *  - 선택 자체의 영속 정체성은 이 인덱스가 아니라 stable (rowId × field) 앵커로 저장한다
+ *    (C0.5) — CellRange 는 어디까지나 "현재 화면에 투영된" 사각형 표현이다.
+ */
 export interface CellRange {
     startRow: number;
     endRow: number;
     startCol: number;
     endCol: number;
 }
+export interface RangeSelectionOptions {
+    /** 기본 selection==='cells' 와 동치 */
+    enabled?: boolean;
+    /** 기본 true — 핸들 표시/드래그 */
+    fillHandle?: boolean;
+    /** 기본 false — Ctrl 멀티 rect(Full, 미구현) */
+    multiRange?: boolean;
+    /** 기본 24(px) — autoscroll 밴드 폭 */
+    autoScrollEdge?: number;
+    /** 기본 true — false 면 항상 copy(시리즈 감지 비활성) */
+    seriesFill?: boolean;
+    /** 기본 false — 그룹/트리 모드 범위선택(MVP 비활성) */
+    enabledInTreeGroup?: boolean;
+    /** 기본 false — 수식 대상 덮어쓰기(C3.2 opt-in) */
+    fillOverwriteFormula?: boolean;
+}
+export interface RangeFillEvent {
+    source: CellRange;
+    target: CellRange;
+    mode: 'copy' | 'series';
+    written: Array<{
+        rowIndex: number;
+        field: string;
+        oldValue: any;
+        newValue: any;
+    }>;
+    skippedFormula?: number;
+    /** before 훅에서 true 로 바꾸면 채우기 취소(현재 배선은 이벤트 emit 뒤 즉시 확인) */
+    cancel?: boolean;
+}
+export interface RangeCopyEvent {
+    range: CellRange;
+    text: string;
+}
+export interface RangeChangeEvent {
+    range: CellRange | null;
+}
+export type { FormulaErrorCode } from './formula/types.js';
+/** F3 옵션(C5.1 단일 중첩 — 최상위 flat 키 금지). */
+export interface FormulaOptions {
+    /** 셀 수식 인-셀 '=' 편집 자동 인식 on(기본 false — 회귀 0). setCellFormula API 는 이 값과 무관하게 항상 동작. */
+    enabled?: boolean;
+    /** 참조 정규화 정책(기본 'stable', §3.2). */
+    refMode?: 'stable' | 'relative';
+    /** 나눗셈 소수 자리(기본 30, FormulaEngine 계승). */
+    divisionPrecision?: number;
+    /** 수식 바 표시(P1, 기본 false — 미구현). */
+    formulaBar?: boolean;
+    /** 수식 셀 마커(기본 true — HANMS-09/R-FORMULA-MARKER). */
+    cellMarker?: boolean;
+    /** 편집 시 자동 재계산(기본 true). */
+    autoRecalc?: boolean;
+    onFormulaChange?: (e: FormulaChangeEvent) => void;
+    onFormulaRecalc?: (e: FormulaRecalcEvent) => void;
+    onFormulaError?: (e: FormulaErrorEvent) => void;
+}
+export interface FormulaChangeEvent {
+    rowIndex: number;
+    field: string;
+    formula: string;
+    oldFormula: string | null;
+}
+export interface FormulaRecalcEvent {
+    changed: string[];
+    cycles: number;
+    ms: number;
+    /** Spike-A §8 교훈: 폐포가 임계(500) 초과 시 true(가이드 문서화/모니터링용). */
+    large: boolean;
+}
+export interface FormulaErrorEvent {
+    rowIndex: number;
+    field: string;
+    error: FormulaErrorCode;
+}
+export type { RangeStats } from './range/RangeQuery.js';
+/** masterDetail.renderer 3번째 인자(§6.1). */
+export interface DetailRenderApi<T = any> {
+    grid: OpenGridInstance<T>;
+    rowId: string;
+    /** 현재 그리드의 중첩 깊이(CON-4). 0 = 최상위. */
+    depth: number;
+    collapse: () => void;
+    /** 패널 재측정(Phase2 auto 대비 자리 — MVP 는 no-op 에 가까움). */
+    refresh: () => void;
+}
+/** F2 옵션(C5.1 단일 중첩 — 구 flat `detail*`/`masterDetail:boolean` 은 이 안으로 접힘). */
+export interface MasterDetailOptions<T = any> {
+    /** 기능 on/off. 기본 false. */
+    enabled?: boolean;
+    /** 임의 HTML/컴포넌트를 host 에 주입(§5). subgridOptions 와 동시 지정 시 이 쪽이 우선. */
+    renderer?: (row: T, host: HTMLElement, api: DetailRenderApi<T>) => void | HTMLElement;
+    /** 패널 높이(px). 기본 200. MVP 는 rowHeight 배수로 양자화(EC-10). */
+    height?: number;
+    /**
+     * 'fixed'(기본)만 MVP 에서 동작. 'auto' 는 Spike-B(C12.2) 통과 전 미공개 — 지정해도
+     * DetailManager 가 'fixed' 로 무시 처리하고 1회 console.warn 한다.
+     */
+    heightMode?: 'fixed' | 'auto';
+    /** 기본 true. false = 아코디언(펼침 1개만 허용). */
+    expandMultiple?: boolean;
+    /** 기본 false. true 면 collapse 해도 host/instance 캐시를 유지(재펼침 시 재생성 생략). */
+    cache?: boolean;
+    /** 어포던스 위치. 기본 'expander-col'(전용 컬럼). */
+    toggle?: 'expander-col' | 'first-cell';
+    /** 패널 role=region 의 aria-label. 기본 '상세 내용'. */
+    ariaLabel?: string;
+    /** 중첩 깊이 한계(CON-4/FR-10). 기본 2. */
+    maxDepth?: number;
+    /** 지정 시 height 대신 이 값을 슬롯수(정수, 최소 1)로 직접 사용. */
+    detailRowCount?: number;
+    /** renderer 미지정 시: 자식 OpenGrid 를 이 옵션으로 자동 생성(§5 ②). */
+    subgridOptions?: GridOptions<any>;
+}
+/** rowExpand/rowCollapse payload(C5.2, §6.3). */
+export interface RowExpandEvent<T = any> {
+    /** flat/visual index(C0.2). */
+    rowIndex: number;
+    rowId: string;
+    row: T;
+    host: HTMLElement | null;
+}
 export interface RendererDef {
     type: RendererType;
     [key: string]: any;
@@ -281,12 +415,31 @@ export interface GridOptions<T = any> {
     autoHeight?: boolean;
     fillWidth?: boolean;
     defaultColumnWidth?: number;
+    /**
+     * 뷰포트 안전장치(옵트인, 기본 undefined = OFF = 기존 동작 완전 불변).
+     * 호스트가 그리드 컨테이너 조상 체인에 확정 높이(definite height)를 주지 않으면
+     * 내부 스페이서(totalRows×rowHeight)가 컨테이너를 전체 콘텐츠 크기로 부풀리고,
+     * ResizeObserver 되먹임으로 windowing 이 무력화되어 전 행이 DOM 렌더되는 폭주가 발생한다
+     * (대량 데이터일수록 재앙적). 이 값을 지정하면, 컨테이너가 전 콘텐츠를 다 담는 "언바운드"
+     * 상태로 감지될 때에 한해 윈도잉 뷰포트 높이를 이 값(px)으로 클램프해 폭주를 차단한다.
+     * 정상적으로 확정 높이가 있는 바운드 컨테이너에는 영향이 없다.
+     * 1순위 권장은 컨테이너/그리드에 확정 height 를 주는 것이며, 이 옵션은 안전망이다.
+     */
+    fallbackViewportHeight?: number;
     editable?: boolean;
     editMode?: 'click' | 'dblclick' | 'none';
     history?: boolean;
     historySize?: number;
     selection?: SelectionMode;
     clipboard?: boolean;
+    /** F1: 범위 선택 + 채우기 핸들(C5.1 단일 중첩 — 최상위 flat 키 금지). */
+    rangeSelection?: RangeSelectionOptions;
+    /** F3: 셀 수식(C5.1 단일 중첩). */
+    formula?: FormulaOptions;
+    /** F2: 마스터/디테일(C5.1 단일 중첩). */
+    masterDetail?: MasterDetailOptions<T>;
+    /** F4: 그리드 데이터 통합 차트(C5.1 단일 중첩). 타입은 chart/types 순환-안전 type-only import. */
+    chart?: import('./chart/types.js').ChartGlobalOptions;
     sortable?: boolean;
     multiSort?: boolean;
     filterable?: boolean;
@@ -334,6 +487,15 @@ export interface GridOptions<T = any> {
     onEditBefore?: (e: EditEvent<T>) => boolean;
     onRowClick?: (e: RowEvent<T>) => void;
     onSelectionChange?: (e: SelectionEvent<T>) => void;
+    /** F1: 범위 rects 변경 시(C4, F4 라이브 소비) */
+    onRangeChange?: (e: RangeChangeEvent) => void;
+    /** F1: 채우기 커밋 결과(§6.3) */
+    onRangeFill?: (e: RangeFillEvent) => void;
+    /** F1: 범위 복사 시(§6.3) */
+    onRangeCopy?: (e: RangeCopyEvent) => void;
+    /** F2: 행 상세 패널 펼침/접힘 시(C5.1 on* 버킷). */
+    onRowExpand?: (e: RowExpandEvent<T>) => void;
+    onRowCollapse?: (e: RowExpandEvent<T>) => void;
     onSortChange?: (e: SortEvent) => void;
     onFilterChange?: (e: FilterEvent) => void;
     onScroll?: (e: ScrollEvent) => void;
@@ -393,6 +555,11 @@ export type CellSerializerFn = (value: any, col: any, row: any) => any;
 export type GroupKeyFn = (row: any, remainingFields: string[]) => any;
 /** 집계 연산. null 반환 시 기본 SUM/AVG/COUNT/MAX/MIN 분기로 폴백. */
 export type SummaryOpFn = (op: string, nums: any[], field: string) => number | null;
+/**
+ * F1 채우기 시리즈 커스텀 리졸버 슬롯(C5.3, 예약). 사용자가 날짜/커스텀 시리즈를 주입할 수 있다.
+ * ⚠️ 슬롯 등록 경로만 확보되어 있으며, RangeSelectionManager/FillEngine 소비 배선은 F1-b(Full) 대상.
+ */
+export type FillSeriesResolverFn = (sourceLine: any[], k: number, axisSign: 1 | -1) => any;
 /** 슬롯명 → 시그니처 매핑. */
 export interface StrategyMap {
     sortComparator: SortComparatorFn;
@@ -401,6 +568,7 @@ export interface StrategyMap {
     cellSerializer: CellSerializerFn;
     groupKeyFn: GroupKeyFn;
     summaryOp: SummaryOpFn;
+    fillSeriesResolver: FillSeriesResolverFn;
 }
 /** 호출가능 + .strategy 멤버를 가진 하이브리드 override API. */
 export interface OverrideApi<T = any> {
@@ -439,6 +607,21 @@ export interface OpenGridInstance<T = any> {
     getDisplayValue(rowIndex: number, field: string): string;
     writeCell(rowIndex: number, field: string, value: any): void;
     getRowAt(rowIndex: number): T;
+    /** flat/visual index ↔ data 리졸버. F1/F3/F4 는 이 모델을 경유해 대상을 해소한다. */
+    getFlatRowModel(): import('./FlatRowModel.js').FlatRowModel;
+    /** 배치 쓰기 시작 — 이후 writeCell 들의 render/dataChange 를 지연·coalesce(reentrant). */
+    beginBatch(): void;
+    /** 배치 종료 — 배치 중 쓰기가 있었으면 1회 render + 1회 coalesced dataChange. */
+    endBatch(): void;
+    /**
+     * beginBatch+루프+endBatch 래퍼. rowIndex 는 flat index — kind!=='data' 대상(group/tree/
+     * detail 의사행)은 쓰기 전에 skip 한다(C0.3 쓰기 안전). 반환값 = 건너뛴 셀 수.
+     */
+    writeCells(patches: Array<{
+        rowIndex: number;
+        field: string;
+        value: any;
+    }>): number;
     getChanges(): {
         added: T[];
         edited: T[];
@@ -480,6 +663,64 @@ export interface OpenGridInstance<T = any> {
     getActiveRow(): number;
     activate(index: number): void;
     deselect(): void;
+    /** 정규화 rects(없으면 []). MVP 는 길이 ≤1. */
+    getRangeSelection(): CellRange[];
+    /** = getRangeSelection()[0] ?? null(C4, F4 소비). */
+    getActiveRange(): CellRange | null;
+    setRangeSelection(range: CellRange | CellRange[]): void;
+    clearRangeSelection(): void;
+    /** 현재 활성 범위의 값 2D 배열(FR-6, F4 필수 계약). */
+    getRangeValues(): any[][];
+    /** 현재 활성 범위 숫자 셀의 OGDecimal 기반 통계(FR-6, F4 필수 계약). */
+    getRangeStats(): _RangeStats | null;
+    /** source→target 채우기(배치 경유, C2). axis 는 두 rect 상대 위치로 추론. */
+    fillRange(source: CellRange, target: CellRange, mode?: 'copy' | 'series'): void;
+    createChart(config: import('./chart/types.js').ChartConfig): import('./chart/types.js').ChartInstance;
+    getCharts(): import('./chart/types.js').ChartInstance[];
+    destroyCharts(): void;
+    /** "=A1+B2" 형태. rowIndex 는 flat(C0), 내부 즉시 stable rowId 로 정규화. */
+    setCellFormula(rowIndex: number, field: string, formula: string): void;
+    getCellFormula(rowIndex: number, field: string): string | null;
+    hasCellFormula(rowIndex: number, field: string): boolean;
+    /** 수식 제거(값은 유지). */
+    clearCellFormula(rowIndex: number, field: string): void;
+    getCellError(rowIndex: number, field: string): FormulaErrorCode | null;
+    /** 디버깅용 — 이 셀을 참조하는(종속) 셀들. */
+    getDependents(rowIndex: number, field: string): Array<{
+        rowIndex: number;
+        field: string;
+    }>;
+    /** 디버깅용 — 이 셀이 참조하는(선행) 셀들. */
+    getPrecedents(rowIndex: number, field: string): Array<{
+        rowIndex: number;
+        field: string;
+    }>;
+    /** 전체 수식 위상 재계산(setData/컬럼 변경 등). */
+    recalculate(): void;
+    /** 단일 셀 + 종속 폐포만 재계산. */
+    recalculateCell(rowIndex: number, field: string): void;
+    /** C3(F1 fill 전용): srcRowId/srcField 수식의 상대축만 dRow/dCol 오프셋한 새 수식 원문. */
+    offsetFormula(srcRowId: string, srcField: string, dRow: number, dCol: number): string;
+    /** rowRef 는 flat/visual index(C0.2) 또는 stable id. maxDepth 초과 시 거부(announce, FR-10). */
+    expandRow(rowRef: number | {
+        id: string;
+    }): void;
+    collapseRow(rowRef: number | {
+        id: string;
+    }): void;
+    toggleRow(rowRef: number | {
+        id: string;
+    }): void;
+    isRowExpanded(rowRef: number | {
+        id: string;
+    }): boolean;
+    collapseAllDetails(): void;
+    /** 펼쳐진 적 없으면 undefined. renderer 반환값 또는 자동 생성 서브그리드 인스턴스. */
+    getDetailInstance<D = any>(rowRef: number | {
+        id: string;
+    }): D | undefined;
+    /** FR-11: 컬럼/호스트 리사이즈 후 열린 패널 폭을 강제 재동기(보통은 재렌더가 자동 처리). */
+    resyncPanelWidths(): void;
     getChecked(): Array<{
         row: T;
         rowIndex: number;
@@ -575,6 +816,7 @@ export interface ContextMenuItem {
     type?: 'divider';
 }
 export type { FilterSelectColumn, FilterSelectConfig } from './FilterSelect.js';
+export type { FlatRowRef } from './FlatRowModel.js';
 export interface WorksheetDef<T = any> {
     name: string;
     columns?: ColumnDef<T>[];

package/dist/types/index.d.ts

@@ -6,5 +6,6 @@ export { XmlConverter } from './core/XmlConverter.js';
 export type { OrgChartOptions, OrgChartColumnDef } from './core/OrgChart.js';
 export type { TreeNodeIconDef } from './core/types.js';
 export type { FilterSelectConfig, FilterSelectColumn } from './core/FilterSelect.js';
-export type { GridOptions, ColumnDef, OpenGridInstance, CellEvent, CellKeyEvent, EditEvent, RowEvent, SortItem, FilterItem, ExportOptions, FooterDef, SummaryOptions, RendererDef, EditorDef, DataType, SelectionMode, SortDir, Position, TriggerContext, TriggerHandler, TriggerEvent, } from './core/types.js';
+export type { GridOptions, ColumnDef, OpenGridInstance, CellEvent, CellKeyEvent, EditEvent, RowEvent, SortItem, FilterItem, ExportOptions, FooterDef, SummaryOptions, RendererDef, EditorDef, DataType, SelectionMode, SortDir, Position, TriggerContext, TriggerHandler, TriggerEvent, CellRange, FlatRowRef, } from './core/types.js';
 export type { XmlParseOptions, XmlStringifyOptions, SapParseResult, } from './core/XmlConverter.js';
+export type { ChartType, ChartSource, ChartSeriesSpec, ChartSeries, ChartDataModel, ChartConfig, ChartInstance, ChartGlobalOptions, ChartPoint, ChartAdapter, ChartRenderSpec, ChartTheme, A11yTableModel, } from './core/chart/types.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-grid",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "description": "Ultra-light data grid with a zero-dependency core — works with React, Vue, Angular, jQuery, or vanilla JS. MIT-licensed, endlessly customizable, with an AI-friendly override guide.",
   "type": "module",
   "main": "dist/open-grid.cjs",