open-grid 1.1.0 → 1.2.0

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

@@ -0,0 +1,128 @@
+import { DataLayer } from './DataLayer.js';
+import { FlatRowModel } from './FlatRowModel.js';
+import { VirtualScroll } from './VirtualScroll.js';
+import { Pagination } from './Pagination.js';
+import { ColumnLayout } from './ColumnLayout.js';
+import { RowManager } from './RowManager.js';
+import { GroupTreeManager } from './GroupTreeManager.js';
+import { TriggerManager } from './TriggerManager.js';
+import { GridOptions, Position } from './types.js';
+/**
+ * R4(§3.4, R-9a/R-9b): 모든 데이터 변경의 mutate→render→emit 꼬리를 단일 초크포인트
+ * `commit(spec)` 로 수렴시키기 위한 명시 데이터계약(CommitSpec DTO). 각 mutator 의
+ * **관측 가능한 발화 순서 차이는 정규화 대상이 아니라 이 필드들로 인코딩**한다
+ * (R-9c 회귀0: R0 골든 `mutation-event-sequence.test.ts` 순서 보존).
+ *
+ * - `totals`  : VS/Pagination 행수 갱신. 'count'=현재 행수(insert/delete/push/unshift),
+ *               'zero'=0(clearData). 생략=미갱신(writeCell/setData — 행수 불변 or 인라인 처리).
+ * - `renderMode` : 'sync-window'=`_doRender(...visRange)`(insert/delete/write/endBatch),
+ *               'full'=`_doRender(0,-1)`(clearData),
+ *               'async-vs'=명령형 렌더 없음. setData 는 setTotalRows/rebuild 로 VS 가
+ *               rAF 스케줄(비동기)하므로 `commit` 은 동기 `_doRender` 를 **하지 않는다**.
+ * - `emitBeforeRender` : true=emit 을 render 앞에(writeCell/endBatch — 현행 순서), 기본 false=render 먼저(insert/delete).
+ * - `emitPayload` : `emit('dataChange', …)` 페이로드 지연 평가(thunk). getData() 시점을
+ *               현행과 동일(render 뒤 or 앞)하게 유지 + 명시 onDataChange 재호출 시 2회 평가 보존.
+ * - `fireOnDataChangeExplicitly` : true=`_options.onDataChange?.()` 를 **명시 재호출**(bound listener 와 합쳐 DOUBLE-fire).
+ *               row mutator=true, setData/clearData=false(bound listener 로 ONCE).
+ * - `flushFormula` : true=emit 전에 `_flushFormulaRecalc()`(writeCell/endBatch).
+ * - `preRender` : render 직전 훅(deleteRow 의 removedRowId invalidate 루프).
+ * - `coalescable` : true 인 커밋만 배치 개구 중 render/emit 을 no-op 하고 `_batchDirty` 를 세운다.
+ *               **writeCell 만 원래 배치를 감지**했으므로 나머지 mutator(coalescable 생략)는
+ *               배치 안에서도 즉시 렌더(현행 보존 — 배치 게이트를 전 mutator 로 확대하지 않는다).
+ */
+export interface CommitSpec {
+    totals?: 'count' | 'zero';
+    renderMode: 'sync-window' | 'full' | 'async-vs';
+    emitBeforeRender?: boolean;
+    emitPayload: () => any;
+    fireOnDataChangeExplicitly?: boolean;
+    flushFormula?: boolean;
+    preRender?: () => void;
+    coalescable?: boolean;
+}
+/**
+ * R6(§3.1 C5, §6-R6): 데이터 변경 표면(setData/insert/push/delete/writeCell/writeCells + 배치 API)
+ * 와 R4 가 도입한 단일 커밋 초크포인트 `commit(CommitSpec)` 를 `OpenGrid` God object 에서
+ * **동작 불변**으로 옮긴 것. `OpenGrid` 는 얇은 위임 공개 메서드만 남긴다(공개 API 불변).
+ *
+ * 스트랭글러 원칙(A2): DataLayer 는 여전히 `OpenGrid` 가 소유하며, 여기에는 `*Deps`
+ * 클로저 역전 패턴으로 **주입**만 된다. **서비스는 렌더를 직접 모른다**(Yourdon I/O 분리):
+ * render 는 주입된 `doRenderWindow`/`doRenderFull` 콜백으로만 유발한다. 값(vs/pagination/recalc
+ * 등)은 늦은-null / 재할당(worksheet 전환)을 견디도록 전부 getter 클로저로 읽는다.
+ * 배치 코얼레싱(`_batchDepth`/`_batchDirty`) 시맨틱은 R4 와 1:1 동일하다(회귀 0).
+ */
+export interface MutationServiceDeps<T extends Record<string, any> = any> {
+    getData: () => DataLayer<T>;
+    getVs: () => VirtualScroll | null;
+    getPagination: () => Pagination | null;
+    getFlatModel: () => FlatRowModel;
+    getColLayout: () => ColumnLayout<T>;
+    getContainer: () => HTMLElement;
+    getTrigMgr: () => TriggerManager;
+    getRowMgr: () => RowManager<T>;
+    getGrpMgr: () => GroupTreeManager<T>;
+    getOptions: () => Required<GridOptions<T>>;
+    /** EventEmitter fan (this.emit) — 'dataChange'/'editEnd'/'writeCellsSkip'. */
+    emit: (event: string, payload?: any) => void;
+    /** aria-live announce (C8.1 공용 인프라). */
+    announce: (msg: string) => void;
+    /** i18n: 데이터 로드/스킵 announce 해석. / i18n: resolve data load/skip announces. */
+    t: (key: string, params?: Record<string, string | number>) => string;
+    /** sort/filter 재적용(setData). */
+    applyFilters: () => void;
+    /** writeCell/endBatch 커밋 emit 직전 수식 dirty seed 소비. */
+    flushFormula: () => void;
+    /** 현재 가시 범위 렌더(this._doRender(...this._visRange())). 서비스는 렌더 내부를 모른다. */
+    doRenderWindow: () => void;
+    /** 전체 렌더(this._doRender(0, -1)) — clearData full 모드. */
+    doRenderFull: () => void;
+    /** setData: 수식 dirty seed clear + RecalcCoordinator 재생성(rowId 재발급 대응). */
+    resetFormulaState: () => void;
+    /** writeCell: 값이 바뀐 셀을 수식 dirty seed 로 적립(kind==='data' 일 때만). */
+    seedFormulaDirty: (rowIndex: number, field: string) => void;
+    /** deleteRow: 제거된 rowId 를 deps 로 갖는 수식들을 #REF 로 무효화(preRender). */
+    invalidateRemovedRows: (rowIds: string[]) => void;
+    /** deleteRow: 제거 전 flat index 의 안정 rowId 확보. */
+    getRowIdAt: (rowIndex: number) => string | undefined;
+}
+export declare class MutationService<T extends Record<string, any> = any> {
+    private _deps;
+    /** reentrant 카운터. 0 초과면 배치 중(writeCell 이 render/dataChange 를 지연). */
+    private _batchDepth;
+    /** 배치 구간 중 실제 쓰기가 1건이라도 있었는지(빈 배치는 endBatch 에서 아무 것도 안 함). */
+    private _batchDirty;
+    constructor(deps: MutationServiceDeps<T>);
+    /**
+     * R4(§3.4, R-9a): 단일 커밋 초크포인트. mutate 완료 후의 totals→(preRender)→flush→render/emit
+     * 꼬리를 여기로 수렴. **관측 순서는 spec 필드로 인코딩**(정규화 아님 — R0 골든 diff=0).
+     * 배치 코얼레싱을 내재화: `coalescable` 커밋은 배치 개구 중 render/emit 을 지연하고
+     * `_batchDirty` 만 세운다(가장 바깥 endBatch 에서 1회 flush).
+     */
+    commit(spec: CommitSpec): void;
+    setData(data: T[]): void;
+    insertRow(item: Partial<T>, position?: Position): void;
+    pushRow(items: Partial<T> | Partial<T>[]): void;
+    deleteRow(rowIndex: number | number[]): void;
+    writeCell(rowIndex: number, field: string, value: any): void;
+    /**
+     * 배치 쓰기 시작(C2.1). 이후 writeCell 호출들은 render/dataChange 를 지연·coalesce 한다.
+     * 중첩 호출은 카운팅(reentrant) — 가장 바깥 endBatch 에서만 실제로 flush 된다.
+     */
+    beginBatch(): void;
+    /**
+     * 배치 종료(C2.1). 카운터가 0 이 되는 시점에 한해 배치 중 발생한 쓰기가 있으면
+     * _doRender 1회 + dataChange 1회를 발생시킨다(둘 다 0회 또는 1회 — 폭주 차단).
+     */
+    endBatch(): void;
+    /**
+     * beginBatch+루프+endBatch 래퍼(C2.1). patches 의 rowIndex 는 flat index — 대상이
+     * FlatRowModel.resolveFlatRow 로 해소해 kind!=='data' (group/tree/detail 의사행)이면
+     * 쓰기 전에 skip 한다(C0.3 쓰기 안전, filler 에 writeCell 절대 금지).
+     * 건너뛴 셀 수를 반환하고, 1건이라도 있으면 announce + 'writeCellsSkip' 이벤트로 표면화한다.
+     */
+    writeCells(patches: Array<{
+        rowIndex: number;
+        field: string;
+        value: any;
+    }>): number;
+}