open-grid 1.0.8 → 1.1.0

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

@@ -0,0 +1,181 @@
+import { CellRange } from '../types.js';
+/**
+ * Phase1 MVP = 'bar'|'line'. 나머지는 Phase2/3 예약(타입만 선언, 미구현).
+ *
+ * ⚠️ 'bar-stacked': 공개 타입으로 노출되어 있으나 내장(builtin-canvas) 렌더러는 현재 스택
+ * 누적을 구현하지 않는다 — 지정해도 'bar-grouped'와 동일하게 그룹형(side-by-side)으로
+ * 폴백 렌더된다(CanvasAdapter._computeGeometry). 하위호환을 위해 타입 자체는 유지한다.
+ */
+export type ChartType = 'bar' | 'line' | 'area' | 'pie' | 'doughnut' | 'bar-stacked' | 'bar-grouped';
+export interface ChartSeriesSpec {
+    field: string;
+    name?: string;
+    color?: string;
+    pattern?: ChartSeries['pattern'];
+    type?: 'bar' | 'line' | 'area';
+}
+export type ChartSource = {
+    kind: 'range';
+    range?: CellRange;
+} | {
+    kind: 'selection';
+} | {
+    kind: 'checked';
+} | {
+    kind: 'all';
+} | {
+    kind: 'columns';
+    category?: string;
+    series: Array<string | ChartSeriesSpec>;
+};
+export type ChartAggregateOp = 'sum' | 'avg' | 'count' | 'min' | 'max';
+export type ChartAggregate = ChartAggregateOp | ((values: number[], category: string) => number);
+export interface A11yTableModel {
+    /** aria-label 요약 캡션 */
+    caption: string;
+    /** ['category', ...series names] */
+    colHeaders: string[];
+    /** [category, v1, v2, ...] — locale 포맷 문자열 */
+    rows: string[][];
+}
+export interface ChartSeries {
+    /** 범례 라벨(기본값 = 원본 컬럼 header/field) */
+    name: string;
+    /** categories 와 동일 순서로 정렬. 결측=null */
+    data: Array<number | null>;
+    color?: string;
+    /** 색 외 구분(HANMS-19) */
+    pattern?: 'solid' | 'hatch' | 'dot' | 'cross';
+}
+export interface ChartDataModelMeta {
+    sourceKind: ChartSource['kind'];
+    /** 원본 포인트(행) 수 */
+    total: number;
+    /** LTTB 다운샘플 또는 category 집계로 축약됐는가 → 배지(§C) */
+    sampled: boolean;
+    sampledFrom?: number;
+    sampledTo?: number;
+    aggregatedOp?: 'sum' | 'avg' | 'count' | 'min' | 'max' | 'custom';
+    pieReducedToFirst?: boolean;
+    negativesAbsInPie?: boolean;
+    /** SR 폴백 — extractor 가 렌더러와 무관하게 항상 채운다(§B 하드 게이트) */
+    a11yTable: A11yTableModel;
+}
+export interface ChartDataModel {
+    categories: string[];
+    series: ChartSeries[];
+    meta: ChartDataModelMeta;
+}
+export interface ChartTheme {
+    primary: string;
+    border: string;
+    text: string;
+    bg: string;
+    gridLine: string;
+    fontFamily: string;
+    fontSize: number;
+    palette: string[];
+}
+export interface ChartRenderSpec {
+    type: ChartType;
+    title?: string;
+    legend?: boolean | {
+        position: 'top' | 'bottom' | 'left' | 'right';
+    };
+    tooltip?: boolean;
+    axis?: {
+        xLabel?: string;
+        yLabel?: string;
+        yMin?: number;
+        yMax?: number;
+        stacked?: boolean;
+    };
+    palette?: string[];
+    theme: ChartTheme;
+    numberFormat?: (v: number, ctx: {
+        axis: 'x' | 'y' | 'tooltip' | 'legend';
+        field?: string;
+    }) => string;
+    a11y: A11yTableModel;
+}
+export interface ChartPoint {
+    seriesName: string;
+    category: string;
+    value: number | null;
+    index: number;
+    rowId?: string;
+}
+export interface ChartAdapter {
+    readonly id: string;
+    init(host: HTMLElement, spec: ChartRenderSpec): Promise<void>;
+    render(model: ChartDataModel, spec: ChartRenderSpec): void;
+    resize(width: number, height: number): void;
+    toBlob?(mime?: string): Promise<Blob | null>;
+    onPointClick?(cb: (p: ChartPoint) => void): void;
+    destroy(): void;
+}
+/** createChart 반환 핸들(§6). 구현은 ChartManager. */
+export interface ChartInstance {
+    readonly id: string;
+    update(patch?: Partial<ChartConfig>): void;
+    /**
+     * 모델을 재추출하고 렌더 스펙(테마 포함)을 재스냅샷해 재렌더한다(§5.3). 그리드는 테마 변경
+     * 이벤트를 발행하지 않으므로(`setTheme`/`setThemeVar`는 CSS 만 갱신) 다크모드 토글처럼 데이터
+     * 변화 없는 순수 테마 전환 후에는, 열려 있는 각 차트에 대해 이 메서드를 호출해야 새 테마
+     * (색·글꼴·팔레트)가 재적용된다. `update()`/`setType()`도 내부적으로 동일 경로를 탄다.
+     */
+    refresh(): void;
+    setType(type: ChartType): void;
+    destroy(): void;
+    toBlob(mime?: string): Promise<Blob | null>;
+    getModel(): ChartDataModel;
+    on(ev: 'chartRender' | 'chartPointClick', cb: (...a: any[]) => void): void;
+}
+/** GridOptions.chart 로 중첩되는 전역 옵션(C5.1, 최상위 flat 키 금지). */
+export interface ChartGlobalOptions {
+    enabled?: boolean;
+    defaultEngine?: 'builtin' | 'chartjs' | 'echarts';
+    defaultType?: ChartType;
+    placement?: 'docked' | 'modal' | 'inline' | 'floating';
+    maxPoints?: number;
+    debounceMs?: number;
+    palette?: string[];
+    numberFormat?: (v: number, ctx: {
+        axis: 'x' | 'y' | 'tooltip' | 'legend';
+        field?: string;
+    }) => string;
+    onChartCreate?: (i: ChartInstance) => void;
+    onChartRender?: (e: {
+        id: string;
+        model: ChartDataModel;
+    }) => void;
+    onChartPointClick?: (e: {
+        id: string;
+        point: ChartPoint;
+    }) => void;
+    onChartDestroy?: (e: {
+        id: string;
+    }) => void;
+}
+export interface ChartConfig {
+    source: ChartSource;
+    type: ChartType;
+    engine?: 'builtin' | 'chartjs' | 'echarts' | ChartAdapter;
+    placement?: 'docked' | 'modal' | 'inline' | 'floating';
+    mount?: HTMLElement;
+    category?: string;
+    series?: Array<string | ChartSeriesSpec>;
+    aggregate?: ChartAggregate;
+    maxPoints?: number;
+    live?: boolean;
+    title?: string;
+    legend?: ChartRenderSpec['legend'];
+    tooltip?: boolean;
+    axis?: ChartRenderSpec['axis'];
+    palette?: string[];
+    numberFormat?: ChartRenderSpec['numberFormat'];
+    size?: {
+        width: number;
+        height: number;
+    };
+}

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

@@ -0,0 +1,48 @@
+/**
+ * DetailGlyph — F2 디테일 expander 글리프/aria 정책 (C10 R-DETAIL-GLYPH, HANMS-06 해소).
+ *
+ * 계약 근거:
+ *  - docs/design/grid-features-2026-07/15_cross_contracts.md C10 "R-DETAIL-GLYPH": detail expander는
+ *    **셰브론(▸/▾) 금지**. 트리 셰브론과 별도 글리프(`⊕/⊖` 또는 `▤ 상세`)+툴팁("상세 보기")+
+ *    aria-label 로 구분. 트리가 **비활성**일 때만 셰브론 허용.
+ *  - docs/design/grid-features-2026-07/11_design_F2_v2.md §4.5(글리프/aria 상세), §1.2 NFR-5(접근성
+ *    측정가능 AC: aria-expanded 토글, aria-controls 연결), §4.3(panel.id 규칙 = aria-controls 타겟),
+ *    C8.4(터치 히트 타겟 ≥44×44 CSS px).
+ *
+ * 렌더 배선(GridRenderer expander 셀)이 이 모듈의 순수 함수/상수를 소비해 실제 DOM 속성을 채운다.
+ * 이 파일은 DOM 을 만들지 않는다 — 문자열/속성 값만 생성.
+ */
+/** 트리 셰브론(▸/▾)과 충돌하지 않는 전용 글리프(C10 기본값). */
+export declare const DETAIL_GLYPH_COLLAPSED = "\u2295";
+export declare const DETAIL_GLYPH_EXPANDED = "\u2296";
+/** 라벨형 대안(옵션) — 기본은 원형 글리프, toggle:'first-cell' 등 배치에서 선택적으로 사용. */
+export declare const DETAIL_GLYPH_LABEL_COLLAPSED = "\u25A4 \uC0C1\uC138";
+export declare const DETAIL_GLYPH_TOOLTIP = "\uC0C1\uC138 \uBCF4\uAE30";
+/** C8.4: expander 히트 타겟 최소 CSS px(가로/세로). */
+export declare const DETAIL_EXPANDER_MIN_HIT_TARGET_PX = 44;
+export interface DetailGlyphInfo {
+    /** 화면에 그릴 문자(셰브론 아님, C10). */
+    glyph: string;
+    /** expander 자체 aria-label(NFR-5, HANMS-06 — SR 에서 트리 토글과 구분). */
+    ariaLabel: string;
+    /** 툴팁 title 속성(C10 "상세 보기" 고정 문구). */
+    title: string;
+}
+/**
+ * 펼침 여부에 따른 글리프/aria-label/title 조합을 반환한다. 트리 셰브론과 절대 겹치지 않는
+ * 문자셋만 사용(C10 R-DETAIL-GLYPH 하드 룰).
+ */
+export declare function getDetailGlyph(expanded: boolean): DetailGlyphInfo;
+/** NFR-5(1): 마스터 행 `aria-expanded` 값(문자열 — DOM setAttribute 그대로 사용). */
+export declare function getMasterRowAriaExpanded(expanded: boolean): 'true' | 'false';
+/**
+ * NFR-5(2)/§4.3: 패널 DOM id 규칙. expander 의 `aria-controls` 와 패널의 `id` 는 반드시 이
+ * 한 함수로만 생성해 두 값의 불일치를 구조적으로 차단한다.
+ */
+export declare function getDetailPanelId(rowId: string): string;
+/**
+ * §4.5 "트리 동시 활성 시 충돌 해소" 규칙의 판별 헬퍼: 트리가 활성화된 그리드에서는 셰브론을
+ * 쓸 수 없다(트리 셰브론과 자리를 공유하지 않도록 렌더 배선이 별도 컬럼/색을 쓰게 강제하는 신호).
+ * 트리 비활성일 때만 셰브론 허용 여부를 true 로 반환한다.
+ */
+export declare function isChevronAllowedForDetail(treeActive: boolean): boolean;

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

@@ -0,0 +1,67 @@
+/**
+ * DetailSplice — 상류 flat 배열에 F2 디테일 head/filler 의사행을 끼워 넣는 순수 함수.
+ *
+ * 계약 근거:
+ *  - docs/design/grid-features-2026-07/11_design_F2_v2.md §2.2/§3.2(단방향 합성 체인의 마지막 단계:
+ *    plain → group/tree(GroupTreeManager 소유) → **detail splice(이 파일)** → FlatRowModel.updateFlatModel),
+ *    §4.1(DetailHeadRow/DetailFillerRow 형태), §7(그룹 헤더엔 미부착·트리 데이터 행엔 허용)
+ *  - docs/design/grid-features-2026-07/15_cross_contracts.md C0.3(FlatRowRef.kind
+ *    'detailHead'/'detailFiller' — filler 에 writeCell 절대 금지의 판별 재료)
+ *
+ * MVP는 (b) 정수-슬롯: 디테일 높이 = span(=ceil(height/rowHeight)) × rowHeight 개의 **정수 rowHeight
+ * 슬롯**으로 표현한다. 1개 head(span 보유) + (span-1)개 filler. VirtualScroll 은 이 슬롯들도 여느
+ * 인덱스와 동일한 rowHeight 로 보고 무변경(CON-1)으로 남는다.
+ *
+ * ⚠️ 이 함수는 실제 GroupTreeManager/FlatRowModel(둘 다 이 작업과 동시에 변경 중)을 import 하지
+ * 않는다. 대신 GridRenderer.ts 가 이미 소비하는 런타임 관례(`_isGroup`/`_isTree` 플래그, 트리 노드의
+ * `.data`)를 로컬 타입 가드로만 재선언해 상류 flat 항목을 분류한다 — 배선 단계에서 실제 등록
+ * 어댑터가 이 함수를 호출한다.
+ */
+/** GroupTreeManager 산출물(GroupRow)과 동형의 최소 구조 — 로컬 판별용(실제 타입 import 안 함). */
+interface GroupLikeItem {
+    _isGroup: true;
+}
+/** TreeEngine TreeNode 와 동형의 최소 구조 — 로컬 판별용(실제 타입 import 안 함). */
+interface TreeLikeItem<T = any> {
+    _isTree: true;
+    data: T;
+}
+/** F2 디테일 head 의사행(§4.1). span 개의 rowHeight 슬롯 중 첫 슬롯 — 실제 패널이 여기 그려진다. */
+export interface DetailHeadItem<T = any> {
+    _isDetailHead: true;
+    _rowId: string;
+    /** 마스터 원본 flat 항목(트리/그룹 컨텍스트 유지용, optional — §4.1). */
+    _masterFlatBase?: T | GroupLikeItem | TreeLikeItem<T>;
+    /** k = ceil(height/rowHeight). 슬롯 총 개수(head 포함). */
+    _span: number;
+}
+/** F2 디테일 filler 의사행(§4.1). span-1 개. renderBody 는 이 인덱스를 만나면 continue(패널이 덮음). */
+export interface DetailFillerItem {
+    _isDetailFiller: true;
+    _rowId: string;
+}
+export type DetailSplicedItem<T = any> = T | GroupLikeItem | TreeLikeItem<T> | DetailHeadItem<T> | DetailFillerItem;
+/** 행별 슬롯수 콜백(옵션) — 지정 시 고정 height 대신 이 값을 사용(반올림 후 ceil 없이 그대로 슬롯수로 채택). */
+export type SlotCountFn<T = any> = (row: T, rowId: string) => number;
+export interface DetailSpliceOptions<T = any> {
+    /** DetailState.expandedRowIds — stable rowId 앵커(정렬/필터 넘어 보존, FR-4/C0.5). */
+    expandedRowIds: ReadonlySet<string>;
+    /** 마스터 후보 row(T)에서 stable rowId 를 뽑는다. undefined/null 이면 해당 항목은 detail 부착 대상에서 제외. */
+    getRowId: (row: T) => string | undefined | null;
+    rowHeight: number;
+    /** masterDetail.height(px). 기본 200. getSlotCount 미지정 시 이 값으로 ceil(height/rowHeight) 계산(EC-10 양자화). */
+    height?: number;
+    /** 지정 시 height 대신 이 콜백으로 슬롯수(정수, 최소 1) 결정 — masterDetail.detailRowCount 류 확장 지점. */
+    getSlotCount?: SlotCountFn<T>;
+}
+/**
+ * baseFlat(plain rows 또는 GroupTreeManager 산출물)을 순회하며, 펼쳐진 stable rowId 를 만난
+ * 마스터 행 **직후**에 `[head, ...filler×(span-1)]` 를 삽입한다(§4.1). 순수 함수 — baseFlat 은
+ * 변경하지 않고 새 배열을 반환한다.
+ *
+ * expandedRowIds 가 비어 있으면(펼침 0/F2 비활성) 항등에 가깝게 동작하되, §3.2 v2 규범대로
+ * "DetailManager는 항상 최종 flat 소유자"이므로 얕은 복사본을 반환한다(호출자가 항상 새 배열을
+ * updateFlatModel 에 넘기는 계약을 일관되게 유지하기 위함 — 참조 동일성에 의존한 버그 예방).
+ */
+export declare function spliceDetails<T = any>(baseFlat: ReadonlyArray<DetailSplicedItem<T>>, opts: DetailSpliceOptions<T>): DetailSplicedItem<T>[];
+export {};

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

@@ -0,0 +1,67 @@
+/**
+ * DetailState — F2 마스터/디테일 펼침 상태 (헤드리스).
+ *
+ * 계약 근거:
+ *  - docs/design/grid-features-2026-07/11_design_F2_v2.md §3.1(DetailManager 상태 부분),
+ *    §6.1(masterDetail.maxDepth/expandMultiple 기본값), §6.3(rowExpand/rowCollapse payload)
+ *  - docs/design/grid-features-2026-07/15_cross_contracts.md C0.5(범위/선택 정체성 = stable-id 앵커 —
+ *    F2 펼침도 동일 원칙), C5.2(이벤트명 `<subject><Verb>` camelCase)
+ *
+ * 책임 경계: 이 파일은 **펼침 상태(Set<rowId>)와 규칙**만 다룬다. DOM/서브그리드 생명주기는
+ * SubgridCache, flat 배열 스플라이스는 DetailSplice 가 담당한다(관심사 분리, Booch 경계).
+ *
+ * ⚠️ FlatRowModel(src/core/FlatRowModel.ts)은 착륙 중인 별도 파일이라 여기서 직접 import 하지 않는다.
+ * rowIndex→rowId 해소는 배선 단계(OpenGrid/DetailManager)에서 FlatRowModel 경유로 수행하고,
+ * 이 클래스는 이미 해소된 stable rowId(string)만 입력받는다.
+ */
+/** FR-6 rowExpand/rowCollapse 이벤트 payload 재료. rowIndex/host 는 배선 단계에서 채운다(§6.3). */
+export interface RowExpandEventPayload {
+    rowIndex: number;
+    rowId: string;
+    row: any;
+    host: HTMLElement | null;
+}
+export interface DetailStateOptions {
+    /** masterDetail.maxDepth, 기본 2 (CON-4/FR-10). */
+    maxDepth?: number;
+    /** masterDetail.expandMultiple, 기본 true. false=아코디언(펼침 1개만 허용). */
+    expandMultiple?: boolean;
+    /** 이 그리드 인스턴스의 현재 중첩 깊이(부모가 자식 생성 시 depth+1 주입, CON-4). 기본 0(최상위). */
+    depth?: number;
+}
+export type DetailToggleResult = 'expanded' | 'collapsed' | 'rejected';
+/**
+ * 펼침 상태 보관소. rowId 는 DataLayer stable id(`_ogRowId` 등) — 정렬/필터로 flat 인덱스가
+ * 바뀌어도 이 Set 의 멤버십은 그대로 보존된다(FR-4, C0.5).
+ */
+export declare class DetailState {
+    private _expanded;
+    private _maxDepth;
+    private _expandMultiple;
+    private _depth;
+    constructor(opts?: DetailStateOptions);
+    /** 읽기 전용 뷰. 소유권은 이 클래스가 유지(외부에서 mutate 금지). */
+    get expandedRowIds(): ReadonlySet<string>;
+    get size(): number;
+    get depth(): number;
+    get maxDepth(): number;
+    get expandMultiple(): boolean;
+    isExpanded(rowId: string): boolean;
+    /** CON-4/FR-10: depth >= maxDepth 면 이 그리드에서는 더 이상 펼칠 수 없다(중첩 깊이 경계). */
+    canExpand(): boolean;
+    /**
+     * rowId 를 펼침 상태로 표시.
+     * - depth 초과(EC-6/FR-10)면 false 반환(거부) — 호출자가 announce() 등 경고를 낸다.
+     * - 이미 펼쳐져 있으면 멱등(true, 재적용 없음 — EC-7 빠른 토글 연타 방어).
+     * - expandMultiple:false(아코디언)면 기존 펼침을 전부 접고 이 rowId 만 남긴다.
+     */
+    expand(rowId: string): boolean;
+    /** rowId 를 접음. 이미 접혀 있었으면 false(no-op 신호, 호출자가 이벤트 emit 여부 판단). */
+    collapse(rowId: string): boolean;
+    /** 토글 1회 = 정확히 하나의 결과(FR-6 "emit 정확히 1회"의 기반). */
+    toggle(rowId: string): DetailToggleResult;
+    /** collapseAllDetails() 배선용. 접힌 rowId 목록을 반환(호출자가 각각 rowCollapse emit 판단). */
+    collapseAll(): string[];
+    /** FR-6 payload 조립 헬퍼(순수 데이터 조립, emit 자체는 배선 단계 EventEmitter 몫). */
+    buildEventPayload(rowId: string, rowIndex: number, row: any, host: HTMLElement | null): RowExpandEventPayload;
+}

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

@@ -0,0 +1,73 @@
+/**
+ * SubgridCache — F2 임베드 서브그리드(디테일 인스턴스) 생명주기 관리 (헤드리스, DOM 비접촉).
+ *
+ * 계약 근거:
+ *  - docs/design/grid-features-2026-07/11_design_F2_v2.md §3.1(DetailEntry: host/instance/built),
+ *    §5(Mount-once + detached 캐시 + 편집중 skip-rebuild — MCCONNELL-04 해소),
+ *    §5(5)(collapse: cache!==true 면 destroy, cache:true 면 host 캐시 유지)
+ *
+ * 핵심 의미론(§5 "핵심 통찰"): `_body.innerHTML=''`(GridRenderer 매 렌더 teardown, CON-2)는
+ * "삭제"가 아니라 "분리"다. 이 클래스는 그 통찰을 **mount-once ≠ detach ≠ delete** 3단계로
+ * 모델링한다:
+ *   1) mount-once  — rowId 당 `adapter.create` 는 정확히 1회만 호출(getOrCreate).
+ *   2) detach/reattach — 매 렌더 teardown/재조립을 생존(파괴 아님, DOM 이동일 뿐).
+ *   3) destroy     — collapse(cache:false) 또는 그리드 destroy 시에만 실제 정리.
+ *
+ * 이 클래스는 DOM 을 직접 만들거나 조작하지 않는다 — 호스트 생성(`hostFactory`)과 실제 마운트/해제
+ * 동작은 전부 `SubgridAdapter` 주입 인터페이스 뒤로 위임한다(렌더 배선 단계가 실 DOM/자식 OpenGrid를
+ * 연결). §5(4) 편집중 skip-rebuild 훅 자리는 `isEditing()` 로 자리만 마련해 둔다(Phase1 배선 대상).
+ */
+/** 서브그리드(또는 임의 렌더러 산출물) 생명주기 훅 — DOM 조작은 이 어댑터 구현체 책임. */
+export interface SubgridAdapter<T = any> {
+    /** rowId 당 정확히 1회 호출(§5 mount-once). host 는 영속 div(재렌더 생존, DetailManager.getDetailHost 산출물). */
+    create(rowId: string, host: HTMLElement): T;
+    /** teardown 직전: host 를 문서에서 분리하되 instance 는 파괴하지 않는다(§5 "분리≠삭제"). */
+    detach(instance: T, host: HTMLElement): void;
+    /** 재조립 시: 동일 host/instance 를 새 패널 wrapper 에 재부착. */
+    reattach(instance: T, host: HTMLElement): void;
+    /** collapse(cache:false) 또는 그리드 destroy 시에만 호출 — 실제 정리(EC-9). */
+    destroy(instance: T, host: HTMLElement): void;
+}
+export interface RemoveOptions {
+    /** masterDetail.cache. true 면 destroy 대신 detach 만 하고 entry 를 유지(재펼침 시 재사용, §5(5)). */
+    cache?: boolean;
+}
+export declare class SubgridCache<T = any> {
+    private adapter;
+    private _entries;
+    constructor(adapter: SubgridAdapter<T>);
+    get size(): number;
+    has(rowId: string): boolean;
+    /**
+     * 최초 펼침: `hostFactory()` 로 영속 host 를 만들고 `adapter.create` 를 **정확히 1회** 호출한다.
+     * 이미 캐시돼 있으면(재펼침, cache:true 로 남아있던 entry) 기존 entry 를 그대로 반환 — create
+     * 재호출 없음(mount-once 보장의 핵심 단언 지점).
+     */
+    getOrCreate(rowId: string, hostFactory: () => HTMLElement): {
+        host: HTMLElement;
+        instance: T;
+    };
+    /** 매 renderBody 재조립 시: 이미 분리돼 있던 entry 만 재부착(파괴됐던 적 없음, §5 핵심 통찰). */
+    reattach(rowId: string): boolean;
+    /** teardown 직전 분리 표시. entry 는 Map 에 남아 GC 되지 않는다(참조 유지 = 생존, §5 핵심 통찰). */
+    detach(rowId: string): boolean;
+    /** 부모 renderBody 진입 시 전체 teardown 흉내(호출자가 skip-rebuild 대상은 미리 걸러 호출). */
+    detachAll(): void;
+    /**
+     * collapse 시 정책 분기(§5(5)): `cache:true` 면 destroy 없이 detach 만(재펼침 시 getOrCreate 가
+     * 재사용). 기본(`cache` 미지정/false)이면 `adapter.destroy` 후 entry 제거(EC-9 누수 차단).
+     */
+    remove(rowId: string, opts?: RemoveOptions): void;
+    getInstance(rowId: string): T | undefined;
+    getHost(rowId: string): HTMLElement | undefined;
+    isAttached(rowId: string): boolean;
+    /**
+     * §5(4) 편집중 skip-rebuild 훅 자리(Phase1, FR-8/NFR-2). 렌더 배선 단계에서 자식 인스턴스가
+     * `isEditing()` 같은 판정을 노출하면 `isEditingFn` 으로 주입해 teardown 대상에서 제외(hoist)할지
+     * 판단하는 데 쓴다. 헤드리스 단계에서는 판정 위임만 제공하고 실제 hoist/원복 로직은 GridRenderer
+     * 배선이 담당한다.
+     */
+    isEditing(rowId: string, isEditingFn?: (instance: T) => boolean): boolean;
+    /** 부모 destroy(EC-9) 또는 collapseAllDetails 시: 남은 전 인스턴스 정리, 누수 차단. */
+    destroyAll(): void;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * src/core/detail — F2 마스터/디테일 헤드리스 코어 배럴.
+ * 계약: docs/design/grid-features-2026-07/11_design_F2_v2.md, 15_cross_contracts.md
+ *
+ * 후속 배선(미포함, 이 디렉터리 범위 밖):
+ *  - GridRenderer.renderBody 의 `_isDetailHead`/`_isDetailFiller` 분기 + full-width 패널 절대배치
+ *  - VirtualScroll.setTotalRows 에 detail 슬롯 반영(spliceDetails 결과 길이)
+ *  - FlatRowModel.registerSplice(spliceDetails 어댑터) 연결
+ *  - OpenGrid 의 expander 셀 렌더(DetailGlyph 소비) + expandRow/collapseRow/toggleRow API 배선
+ */
+export * from './DetailState.js';
+export * from './DetailSplice.js';
+export * from './SubgridCache.js';
+export * from './DetailGlyph.js';

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

@@ -0,0 +1,15 @@
+import { AstNode, CellKey, CellValue, FormulaErrorCode, FormulaGridAccessor } from './types.js';
+export interface EvalOutcome {
+    value: CellValue;
+    error: FormulaErrorCode | null;
+    approx: boolean;
+    touched: Set<CellKey>;
+}
+export interface EvalOptions {
+    divisionPrecision?: number;
+}
+/** 정규화된 AST 하나를 평가한다. 절대 throw 하지 않는다(에러는 outcome.error 로 격리, F3-R24). */
+export declare function evaluate(ast: AstNode, host: {
+    rowId: string;
+    field: string;
+}, accessor: FormulaGridAccessor, opts?: EvalOptions): EvalOutcome;

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

@@ -0,0 +1,43 @@
+import { CellKey } from './types.js';
+export declare class FormulaGraph {
+    /** cellKey(수식) → 그 수식이 참조하는 선행 셀 키 집합. */
+    private readonly _precedents;
+    /** cellKey(임의: 수식이든 값 리프든) → 그 키를 참조하는 수식 키 집합(dirty 전파 방향). */
+    private readonly _dependents;
+    /** rowId → 그 rowId의 "어떤 field"든 deps 로 가진 수식 키 집합(행 삭제 역조회, §5.1). */
+    private readonly _byRowId;
+    /** field → 그 field 를 deps 로 가진 수식 키 집합(열 삭제 역조회). */
+    private readonly _byField;
+    private _addEdge;
+    private _removeEdgesFrom;
+    /** key(수식 셀)의 선행 엣지를 deps 로 완전히 교체한다(§5.1 addFormula). */
+    addFormula(key: CellKey, deps: Set<CellKey>): void;
+    /** 수식 삭제(clearCellFormula) — 엣지 + 역인덱스 정리. */
+    removeFormula(key: CellKey): void;
+    isFormula(key: CellKey): boolean;
+    getPrecedents(key: CellKey): CellKey[];
+    getDependents(key: CellKey): CellKey[];
+    /**
+     * dirty 폐포(BFS): seeds 로부터 도달 가능한 모든 dependents(수식 노드만, dependents 맵의
+     * value 는 항상 수식 키이므로 자동 보장). seed 자신이 수식이면 폐포에 포함한다
+     * (§5.3 "수식 셀 편집 → 자신 + dependents dirty").
+     */
+    getDependentsClosure(seeds: CellKey[]): CellKey[];
+    /** Kahn 위상정렬(subset 내부 선행수 기준, §5.4). 잔여 노드 = 사이클 구성원. */
+    topoOrder(subset: CellKey[]): {
+        order: CellKey[];
+        cycles: CellKey[];
+    };
+    /**
+     * 삭제 무효화 역조회(§5.1/F3-R28 P0): 특정 rowId(전체 field, field 생략 시) 또는
+     * (rowId,field) 특정 셀을 deps 로 가진 수식 키들. removeRow/removeColumn 후크가
+     * 이 결과를 onValuesChanged 의 seed 로 넘기면(대상 rowId/field 는 이미 grid 에서
+     * 제거된 상태이므로) 평가 시 accessor.hasRow/hasField 가 false 를 반환해 자연스럽게
+     * #REF 로 귀결한다(별도 특수 처리 없이 일반 재계산 경로 재사용).
+     */
+    formulasReferencing(rowId: string, field?: string): CellKey[];
+    /** 열 삭제 역조회(field 단독 기준, §5.1). */
+    formulasReferencingField(field: string): CellKey[];
+    /** 등록된 모든 수식 키(recalculateAll 전체 재계산용). */
+    allFormulaKeys(): CellKey[];
+}

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

@@ -0,0 +1,6 @@
+import { AstNode } from './types.js';
+/**
+ * 셀 수식 원문(선두 '=' 포함 가능)을 파싱해 AST(원시 참조 노드 포함, 정규화 전)를 만든다.
+ * 정규화(normalizeRefs)는 별도 단계(§3.3)에서 수행한다.
+ */
+export declare function parseFormula(src: string): AstNode;

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

@@ -0,0 +1,17 @@
+import { CellKey, FormulaCell } from './types.js';
+export declare class FormulaStore {
+    private readonly _cells;
+    setFormula(rowId: string, field: string, cell: FormulaCell): void;
+    getFormula(rowId: string, field: string): FormulaCell | undefined;
+    clearFormula(rowId: string, field: string): void;
+    hasFormula(rowId: string, field: string): boolean;
+    getFormulaByKey(key: CellKey): FormulaCell | undefined;
+    getAllFormulaCells(): Array<{
+        rowId: string;
+        field: string;
+        cell: FormulaCell;
+    }>;
+    /** applySort/applyFilter 후크가 dirty 대상으로 모아야 할 range-보유 수식 키(§3.5 P0). */
+    getRangeBearingKeys(): CellKey[];
+    size(): number;
+}

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

@@ -0,0 +1,85 @@
+import { CellKey, CellValue, FormulaCell, FormulaErrorCode, FormulaGridAccessor, RefMode } from './types.js';
+import { indexToColLetters } from './normalizeRefs.js';
+import { FormulaStore } from './FormulaStore.js';
+import { FormulaGraph } from './FormulaGraph.js';
+export interface RecalcSummary {
+    changed: CellKey[];
+    cycles: number;
+    ms: number;
+}
+export interface RecalcCoordinatorOptions {
+    accessor: FormulaGridAccessor;
+    setComputedValue: (rowId: string, field: string, value: CellValue) => void;
+    onFormulaError?: (rowId: string, field: string, error: FormulaErrorCode) => void;
+    refMode?: RefMode;
+    divisionPrecision?: number;
+}
+export declare class RecalcCoordinator {
+    readonly store: FormulaStore;
+    readonly graph: FormulaGraph;
+    private readonly _accessor;
+    private readonly _setComputedValue;
+    private readonly _onFormulaError;
+    private readonly _refMode;
+    private readonly _prec;
+    constructor(opts: RecalcCoordinatorOptions);
+    /** src("=...")를 파싱+정규화한다. 파싱 자체가 실패하면 #ERR/#NAME 을 담은 error AST로 폴백. */
+    compile(src: string, host: {
+        rowId: string;
+        field: string;
+    }): {
+        ast: FormulaCell['ast'];
+        hasRangeRef: boolean;
+    };
+    /**
+     * setCellFormula(§8.2) — 저장 후 즉시 평가하고, 기존 dependents 가 있으면 함께 dirty 처리.
+     *
+     * ⚠️ 순서가 중요하다(사이클 탐지 정합성): 새 수식을 등록하는 바로 그 순간에 사이클이
+     * "완성"될 수 있다(예: A1=B1 이미 있고 지금 B1=A1 을 등록). onValuesChanged 의
+     * topoOrder 는 "그래프에 현재 등록된 엣지"만으로 사이클을 판정하므로, 이 새 수식의
+     * deps 를 그래프에 등록하기 *전에* 배치를 돌리면 방금 완성된 사이클을 놓친다.
+     * 그래서 여기서 먼저 1회 "탐색 평가"(probe)로 실제 deps 를 얻어 그래프 엣지를 확정한
+     * 뒤에야 onValuesChanged(공식 배치, 사이클이면 evaluate 재호출 없이 #CYCLE 로 귀결)를
+     * 호출한다. 신규 수식 등록 1회당 evaluate 호출이 최대 2회(probe+공식)로 늘지만, 이는
+     * "정의 시점" 1회성 비용이며 F3-R21 이 요구하는 "값 편집에 따른 증분 재계산"(steady
+     * state)과는 무관하다(§13 f3.perf.closure 는 신규 등록이 아니라 leaf 값 변경 시나리오).
+     */
+    setCellFormula(rowId: string, field: string, src: string): RecalcSummary;
+    getCellFormula(rowId: string, field: string): string | null;
+    hasCellFormula(rowId: string, field: string): boolean;
+    /** clearCellFormula(§8.2) — 사이드카+그래프에서 제거. 값(row[field])은 그리드 쪽 책임(값 유지). */
+    clearCellFormula(rowId: string, field: string): CellKey[];
+    getCellError(rowId: string, field: string): FormulaErrorCode | null;
+    /** 디버깅용(§8.2 getDependents) — flat 좌표가 아닌 (rowId,field) 그대로 반환(헤드리스 계층). */
+    getDependents(rowId: string, field: string): Array<{
+        rowId: string;
+        field: string;
+    }>;
+    /**
+     * C2 배치 진입점: keys(값이 바뀐 leaf 셀 또는 재평가가 필요한 수식 셀)로부터 dependents
+     * 폐포를 구해 Kahn 위상 1패스로 재계산한다. 삭제 무효화(F3-R28)는 별도 특수 로직 없이,
+     * 호출부가 "삭제된 rowId/field 를 이미 grid 에서 제거한 뒤" 그 dependents 를 keys 로
+     * 넘기면 evaluate 과정에서 accessor.hasRow/hasField 가 false → 자연스럽게 #REF.
+     */
+    onValuesChanged(keys: CellKey[]): RecalcSummary;
+    private _evaluateOne;
+    /** recalculate()(§8.2) — 전체 수식 노드 위상정렬 후 평가(setData/컬럼 변경 등). */
+    recalculateAll(): RecalcSummary;
+    /** applySort/applyFilter 후크가 호출할 편의 메서드 — range 보유 수식 전부 dirty(§3.5 P0). */
+    recalcRangeBearing(): RecalcSummary;
+    /** removeRow 후크 편의 메서드 — 이 rowId 를 deps 로 가진 수식들을 재계산(자연 #REF, §5.1). */
+    invalidateRow(rowId: string): RecalcSummary;
+    /** removeColumn 후크 편의 메서드 — 이 field 를 deps 로 가진 수식들을 재계산(자연 #REF). */
+    invalidateField(field: string): RecalcSummary;
+    /**
+     * srcRowId/srcField 의 저장된 수식에서 "상대(비-$) 축만" dRow/dCol 만큼 오프셋한 새
+     * 수식 원문을 만든다. 절대($) 축은 불변(C3). 대상 위치가 범위를 벗어나면 해당 참조는
+     * "#REF!" 텍스트로 대체된다(Excel 관례, 이 문자열은 재파싱 시 #NAME 이 아니라 명시적
+     * 깨짐을 사용자가 알아볼 수 있게 하기 위한 것 — 실제 파서가 #REF! 토큰 자체를 정식
+     * 문법으로 지원하진 않으므로, F1 배선 시 이 반환값을 그대로 setCellFormula 에 넘기면
+     * 파싱 실패 → #ERR 로 귀결한다는 점을 후속 배선 태스크가 인지해야 한다).
+     */
+    offsetFormula(srcRowId: string, srcField: string, dRow: number, dCol: number): string;
+    private _shiftAst;
+}
+export { indexToColLetters };

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

@@ -0,0 +1,15 @@
+import { AstNode, FormulaGridAccessor, RefMode } from './types.js';
+/** 열문자(A,B,...,Z,AA,...) → 0-based visibleLeaves 인덱스. */
+export declare function colLettersToIndex(letters: string): number;
+/** 0-based visibleLeaves 인덱스 → 열문자(A,B,...,Z,AA,...). offsetFormula/serializeFormula 재사용. */
+export declare function indexToColLetters(index: number): string;
+/**
+ * 파서가 만든 원시 AST(rawRef/rawRange 포함)를 정규화해 ref/range/error 노드로 치환한다.
+ * host = 이 수식이 저장된 셀(현재 행 컨텍스트, FieldRef·상대참조 기준점).
+ */
+export declare function normalizeAst(ast: AstNode, host: {
+    rowId: string;
+    field: string;
+}, accessor: FormulaGridAccessor, refMode?: RefMode): AstNode;
+/** 이 AST가 범위 참조를 포함하는지(§3.5 hasRangeRef, applySort/applyFilter dirty 대상). */
+export declare function computeHasRangeRef(ast: AstNode): boolean;

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

@@ -0,0 +1,7 @@
+/** 수식 리터럴/셀 텍스트가 산술 가능한 숫자 형태인지 판별(정수/소수/과학표기). */
+export declare const NUMERIC_LITERAL_RE: RegExp;
+/**
+ * 과학표기(`1e-5`, `2.5E3`)를 정확한 10진 문자열로 변환한다(부호/자릿수 이동만 사용,
+ * 부동소수점 경유 없음). 과학표기가 아니면 trim만 하여 그대로 반환.
+ */
+export declare function normalizeNumericLiteral(raw: string): string;