open-grid 1.1.1 → 1.2.1

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

@@ -1,31 +1,55 @@
 import { VirtualScroll } from './VirtualScroll.js';
 import { FlatRowModel } from './FlatRowModel.js';
-/** expandRow/collapseRow/toggleRow/isRowExpanded/getDetailInstance 공통 인자(§6.2, C0.2). */
+/** expandRow/collapseRow/toggleRow/isRowExpanded/getDetailInstance 공통 인자(§6.2, C0.2).
+ * / Common argument shape for expandRow/collapseRow/toggleRow/isRowExpanded/getDetailInstance (§6.2, C0.2). */
 export type DetailRowRef = number | {
     id: string;
 };
+/**
+ * DetailManager 가 OpenGrid 서브시스템을 읽기 위해 주입받는 클로저 묶음. / Closures injected into
+ * DetailManager so it can read OpenGrid subsystem state without owning it directly.
+ */
 export interface DetailManagerDeps<T extends Record<string, any> = any> {
-    /** this._options — masterDetail.* 를 이 안에서 읽는다(옵션 자체는 항상 최신값 참조). */
+    /** this._options — masterDetail.* 를 이 안에서 읽는다(옵션 자체는 항상 최신값 참조).
+     * / this._options — reads masterDetail.* from it (always the latest option values). */
     getOptions: () => any;
     /** Phase 0 baseline. registerSplice 로 detail splice 를 등록하고, count()/resolveFlatRow 로
-     *  rowIndex↔rowId 를 해소한다(F2 는 이 모델의 "소유자"가 아니라 "등록자" — C0.3 정정). */
+     *  rowIndex↔rowId 를 해소한다(F2 는 이 모델의 "소유자"가 아니라 "등록자" — C0.3 정정).
+     * / Phase 0 baseline. Registers the detail splice via registerSplice, and resolves
+     *  rowIndex↔rowId through count()/resolveFlatRow (F2 is a "registrant" of this model,
+     *  not its "owner" — C0.3 correction). */
     getFlatModel: () => FlatRowModel;
+    /** 가상 스크롤 인스턴스(마운트 전이면 null). / Virtual scroll instance (null before mount). */
     getVs: () => VirtualScroll | null;
-    /** DataLayer 가 부여한 stable id 필드값(OpenGrid 의 ROW_ID_FIELD). */
+    /** DataLayer 가 부여한 stable id 필드값(OpenGrid 의 ROW_ID_FIELD). / The stable id field value assigned by DataLayer (OpenGrid's ROW_ID_FIELD). */
     getRowId: (row: T) => string;
-    /** stable rowId → 현재 행(삭제됐으면 undefined). DataLayer.getRowById 위임. */
+    /** stable rowId → 현재 행(삭제됐으면 undefined). DataLayer.getRowById 위임. / stable rowId → current row (undefined if deleted). Delegates to DataLayer.getRowById. */
     getRowById: (rowId: string) => T | undefined;
-    /** group/tree rebuild 와 동일한 관용구 — 전체(0..n-1) 재렌더. */
+    /** group/tree rebuild 와 동일한 관용구 — 전체(0..n-1) 재렌더. / Same idiom as group/tree rebuild — re-renders the full (0..n-1) range. */
     doRenderFull: (n: number) => void;
+    /** 그리드 이벤트 발행. / Emit a grid event. */
     emit: (ev: string, payload: any) => void;
+    /** aria-live 영역에 메시지를 공지. / Announce a message via the aria-live region. */
     announce: (msg: string) => void;
-    /** 이 그리드 인스턴스의 중첩 깊이(0=최상위, 부모가 자식 생성 시 depth+1 주입). */
+    /** i18n: 깊이 한계/펼침·접힘 announce 메시지 해석. / i18n: resolve depth-limit & expand/collapse announces. */
+    t: (key: string, params?: Record<string, string | number>) => string;
+    /** 이 그리드 인스턴스의 중첩 깊이(0=최상위, 부모가 자식 생성 시 depth+1 주입). / Nesting depth of this grid instance (0 = top level; a parent injects depth+1 when creating a child). */
     getDepth: () => number;
-    /** masterDetail.renderer 의 DetailRenderApi.grid 에 실어줄 인스턴스. */
+    /** masterDetail.renderer 의 DetailRenderApi.grid 에 실어줄 인스턴스. / Instance handed to DetailRenderApi.grid inside masterDetail.renderer. */
     getGridInstance: () => any;
-    /** masterDetail.subgridOptions(§5 ②) 소비 — 순환 import 회피 위해 OpenGrid.ts 가 주입. */
+    /** masterDetail.subgridOptions(§5 ②) 소비 — 순환 import 회피 위해 OpenGrid.ts 가 주입. / Consumes masterDetail.subgridOptions (§5 ②) — injected by OpenGrid.ts to avoid a circular import. */
     createSubgrid?: (host: HTMLElement, subgridOptions: any, depth: number) => any;
 }
+/**
+ * F2 마스터/디테일 매니저. / F2 master/detail manager.
+ *
+ * 행 펼침 상태(DetailState)를 소유하고, FlatRowModel 합성 체인 끝에 detail head/filler 의사행을
+ * 등록(registerSplice)하며, 펼쳐진 행마다 서브그리드/커스텀 렌더러 host 를 mount-once 로
+ * 생명주기 관리(SubgridCache)한다. / Owns the row expand/collapse state (DetailState), registers
+ * detail head/filler pseudo-rows at the tail of the FlatRowModel composition chain
+ * (registerSplice), and manages the mount-once lifecycle of each expanded row's
+ * subgrid/custom-renderer host (SubgridCache).
+ */
 export declare class DetailManager<T extends Record<string, any> = any> {
     private _d;
     private _state;
@@ -36,37 +60,106 @@ export declare class DetailManager<T extends Record<string, any> = any> {
     private _focusPendingRestore;
     constructor(deps: DetailManagerDeps<T>);
     private _mdOpts;
-    /** masterDetail.enabled 여부(옵션 자체 — 펼침 개수와 무관). */
+    /** masterDetail.enabled 여부(옵션 자체 — 펼침 개수와 무관). / Whether masterDetail.enabled is set (the option itself — independent of how many rows are expanded). */
     get enabled(): boolean;
-    /** §3.2 v2: "isActive" = 기능 on + 실제 펼침 ≥1(FlatRowModel 합성/렌더 분기 판단용). */
+    /** §3.2 v2: "isActive" = 기능 on + 실제 펼침 ≥1(FlatRowModel 합성/렌더 분기 판단용).
+     * / §3.2 v2: "isActive" = feature on AND at least one row expanded (used to branch
+     *  FlatRowModel composition/rendering). */
     get isActive(): boolean;
+    /** 현재 설정된 최대 중첩 깊이. / Currently configured maximum nesting depth. */
     get maxDepth(): number;
     private _resolveRowId;
+    /** stable rowId 기준 펼침 여부. / Whether the row is expanded, keyed by stable rowId.
+     *
+     * @param rowId - 대상 행의 stable id / Stable id of the target row
+     * @returns 펼쳐져 있으면 true / True if the row is expanded
+     */
     isExpandedId(rowId: string): boolean;
+    /** rowRef(flat index 또는 stable id) 기준 펼침 여부. / Whether the row is expanded, keyed by rowRef (flat index or stable id).
+     *
+     * @param ref - flat index 또는 `{ id }` 형태의 행 참조(C0.2) / Row reference as a flat index or `{ id }` (C0.2)
+     * @returns 펼쳐져 있으면 true / True if the row is expanded
+     */
     isRowExpanded(ref: DetailRowRef): boolean;
+    /**
+     * 지정 행을 펼친다. / Expand the given row.
+     *
+     * maxDepth 초과면 렌더러 진입 전에 거부하고(자식 패널 미생성) announce 로 알린다(CON-4/FR-10).
+     * / If maxDepth would be exceeded, the expansion is rejected before reaching the renderer
+     * (no child panel is created) and the rejection is announced (CON-4/FR-10).
+     *
+     * @param ref - flat index 또는 `{ id }` 형태의 행 참조 / Row reference as a flat index or `{ id }`
+     */
     expandRow(ref: DetailRowRef): void;
+    /**
+     * 지정 행을 접는다. / Collapse the given row.
+     *
+     * @param ref - flat index 또는 `{ id }` 형태의 행 참조 / Row reference as a flat index or `{ id }`
+     */
     collapseRow(ref: DetailRowRef): void;
+    /**
+     * 펼침/접힘 상태를 반전한다. / Toggle the row's expanded/collapsed state.
+     *
+     * @param ref - flat index 또는 `{ id }` 형태의 행 참조 / Row reference as a flat index or `{ id }`
+     */
     toggleRow(ref: DetailRowRef): void;
+    /** 펼쳐진 모든 행을 접는다(변경 없으면 no-op). / Collapse every currently expanded row (no-op if none are expanded). */
     collapseAllDetails(): void;
+    /**
+     * 펼쳐진 행의 서브그리드/커스텀 렌더러 인스턴스를 조회한다. / Look up the subgrid or custom-renderer
+     * instance mounted for an expanded row.
+     *
+     * @param ref - flat index 또는 `{ id }` 형태의 행 참조 / Row reference as a flat index or `{ id }`
+     * @returns 마운트된 인스턴스, 없으면 `undefined` / The mounted instance, or `undefined`
+     */
     getDetailInstance<D = any>(ref: DetailRowRef): D | undefined;
     /** FR-11 공개 계약 — 실제로는 리사이즈 이후 발생하는 통상 재렌더가 panel width 를 최신
      *  totalColWidth 로 이미 재계산하므로(§4.3 GridRenderer 가 매 렌더 폭을 새로 그린다), 여기선
-     *  강제 재렌더 1회로 계약을 만족시킨다(중복 상태 없이 단일 진실원 유지). */
+     *  강제 재렌더 1회로 계약을 만족시킨다(중복 상태 없이 단일 진실원 유지).
+     * / FR-11 public contract — in practice, the normal re-render that follows a resize already
+     *  recomputes panel width against the latest totalColWidth (§4.3: GridRenderer redraws width on
+     *  every render), so this simply forces one re-render to satisfy the contract (no duplicate
+     *  state; single source of truth is preserved). */
     resyncPanelWidths(): void;
-    /** GridRenderer 가 detailHead 를 그릴 때 호출 — 영속 host 를 최초 1회만 만들고 이후 재사용. */
+    /** GridRenderer 가 detailHead 를 그릴 때 호출 — 영속 host 를 최초 1회만 만들고 이후 재사용.
+     * / Called by GridRenderer when it draws a detailHead — creates the persistent host only
+     *  once and reuses it thereafter.
+     *
+     * @param rowId - 대상 행의 stable id / Stable id of the target row
+     * @returns 재사용 가능한 host div / A reusable host div
+     */
     getPanelHost(rowId: string): HTMLElement;
     private _buildInstance;
     /** §5(4) skip-rebuild(FR-8/NFR-2, MCCONNELL-04 → Phase1 승격): renderBody teardown 직전
      *  호출된다. 편집 중인 host 는 detach 자체를 회피(document.body 로 hoist, 연결 유지 → blur
-     *  없음) 하고, 그 외는 정상 detach(연결 끊음, 참조는 Map 이 쥐고 있어 파괴 아님). */
+     *  없음) 하고, 그 외는 정상 detach(연결 끊음, 참조는 Map 이 쥐고 있어 파괴 아님).
+     * / §5(4) skip-rebuild (FR-8/NFR-2, MCCONNELL-04 → promoted to Phase1): called immediately
+     *  before renderBody teardown. A host that is currently being edited avoids detach altogether
+     *  (hoisted into document.body, staying connected → no blur); every other host is detached
+     *  normally (disconnected, but not destroyed — the Map still holds the reference). */
     onBeforeTeardown(): void;
+    /** 서브그리드/커스텀 렌더러 인스턴스가 현재 편집 중인지 여부. / Whether the subgrid/custom-renderer
+     * instance for a row is currently being edited.
+     *
+     * @param rowId - 대상 행의 stable id / Stable id of the target row
+     * @returns 편집 중이면 true / True if currently being edited
+     */
     isEditing(rowId: string): boolean;
     /** collapse 직후 렌더가 끝난 뒤 호출 — FR-9: 패널 내부에 포커스가 있었으면 해당 마스터 행의
-     *  expander 로 복원한다. GridRenderer 가 expander 엘리먼트를 렌더한 다음 프레임에 호출. */
+     *  expander 로 복원한다. GridRenderer 가 expander 엘리먼트를 렌더한 다음 프레임에 호출.
+     * / Called right after the render that follows a collapse — FR-9: if focus had been inside the
+     *  panel, restore it to that master row's expander. GridRenderer calls this on the frame after
+     *  it renders the expander element.
+     *
+     * @returns 포커스를 복원해야 할 행의 stable id, 없으면 `null` / Stable id of the row whose focus
+     *  should be restored, or `null`
+     */
     consumePendingFocusRestore(): string | null;
     private _releaseInstance;
     private _splice;
     private _afterToggle;
     private _rebuildAndRender;
+    /** 모든 서브그리드/커스텀 렌더러 인스턴스를 파괴하고 host 캐시를 비운다.
+     * / Destroy every subgrid/custom-renderer instance and clear the host cache. */
     destroy(): void;
 }

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

@@ -1,29 +1,101 @@
 import { ColumnLayout } from './ColumnLayout.js';
 import { WorksheetManager } from './WorksheetManager.js';
 import { ExportOptions } from './types.js';
+/**
+ * ExportManager 의존성 주입 인터페이스. / Dependency-injection interface for ExportManager.
+ *
+ * OpenGrid 내부 상태(데이터·컬럼·옵션 등)를 export 로직에서 직접 참조하지 않고
+ * 콜백으로만 받도록 분리한다. / Decouples export logic from OpenGrid's internals —
+ * everything is read back through callbacks instead of direct references.
+ */
 export interface ExportDeps<T extends Record<string, any>> {
+    /** 내보낼 전체 행 데이터. / Full row data to export. */
     getData: () => T[];
+    /** 현재 컬럼 레이아웃(가시 리프 컬럼 조회용). / Current column layout (for resolving visible leaf columns). */
     getColLayout: () => ColumnLayout<T>;
+    /** 컬럼별 현재 폭(px) 배열. / Current per-column widths (px). */
     getColWidths: () => number[];
+    /** 그리드 옵션 스냅샷. / Snapshot of grid options. */
     getOptions: () => any;
+    /** 그리드 컨테이너 엘리먼트(테마 CSS 변수 조회용). / Grid container element (for reading theme CSS variables). */
     getContainer: () => HTMLElement;
+    /** 필드별 마스킹 활성 여부. / Whether masking is enabled for a given field. */
     getMaskEnabled: (field: string) => boolean;
+    /** 워크시트 매니저(다중 시트 내보내기용). 없으면 `null`. / Worksheet manager (for multi-sheet export); `null` if absent. */
     getWsManager: () => WorksheetManager<T> | null;
-    /** Phase 2: OverrideKernel.getStrategy 주입(슬롯 cellSerializer 도달용). */
+    /** Phase 2: OverrideKernel.getStrategy 주입(슬롯 cellSerializer 도달용). / Phase 2: injected via OverrideKernel.getStrategy (reaches the `cellSerializer` slot). */
     getStrategy?: <F extends Function>(slot: string, fallback: F) => F;
+    /** i18n: 인쇄 요약행 해석(미주입 시 ko 폴백). / i18n: resolve print summary row (ko fallback when absent). */
+    t?: (key: string, params?: Record<string, string | number>) => string;
+    /** i18n: 로케일 포맷 메타(인쇄 lang·날짜 로케일·Excel 폰트). / i18n: locale format meta (print lang, date locale, Excel font). */
+    getMeta?: () => {
+        intlLocale: string;
+        exportFont?: string;
+    };
 }
+/**
+ * 그리드 데이터 내보내기(Excel/CSV/JSON/인쇄) 관리자. / Manages exporting grid data (Excel/CSV/JSON/print).
+ *
+ * OpenGrid 상태를 {@link ExportDeps} 콜백으로만 읽으며, Excel 계열은 `xlsx-js-style` 을
+ * 동적 import 하여 필요할 때만 로드한다. / Reads OpenGrid state only through {@link ExportDeps}
+ * callbacks; Excel exports dynamically `import()` `xlsx-js-style` so it loads only on demand.
+ */
 export declare class ExportManager<T extends Record<string, any> = any> {
     private _d;
     constructor(deps: ExportDeps<T>);
+    /** @internal 컨테이너의 CSS 커스텀 프로퍼티 값을 읽는다. / Reads a CSS custom property value from the container. */
     private _readCssVar;
+    /** @internal HEX/RGB 색상 문자열을 xlsx-js-style 이 요구하는 6자리 RGB 헥스로 변환. / Converts a HEX/RGB color string into the 6-digit RGB hex xlsx-js-style expects. */
     private _hexToXlsxRgb;
+    /**
+     * 현재 그리드 데이터를 스타일이 적용된 `.xlsx` 로 내보낸다. / Export the current grid data as a styled `.xlsx` file.
+     *
+     * 헤더/데이터 배색은 `styleMode: 'theme'`(기본) 시 그리드 테마 CSS 변수(`--og-*`)에서
+     * 읽어 반영하고, `cellSerializer` override 슬롯이 있으면 셀 값 직렬화를 위임한다.
+     * / When `styleMode: 'theme'` (default), header/data colors are read from the grid's
+     * theme CSS variables (`--og-*`); if an `cellSerializer` override slot is registered,
+     * cell-value serialization is delegated to it.
+     *
+     * @param options - 파일명 문자열 또는 {@link ExportOptions} / A filename string, or {@link ExportOptions}
+     * @example
+     * grid.exportExcel({ filename: 'orders', maskOnExport: true });
+     */
     exportExcel(options?: ExportOptions | string): void;
+    /**
+     * 현재 그리드 데이터를 UTF-8 BOM 포함 CSV 로 내보낸다. / Export the current grid data as a UTF-8 (BOM) CSV file.
+     *
+     * @param options - 파일명 문자열 또는 {@link ExportOptions} / A filename string, or {@link ExportOptions}
+     */
     exportCsv(options?: ExportOptions | string): void;
+    /**
+     * 현재 그리드 데이터를 JSON 파일로 내보낸다. / Export the current grid data as a JSON file.
+     *
+     * @param options - 파일명 문자열 또는 `filename` 을 담은 옵션 / A filename string, or an options object with `filename`
+     */
     exportJson(options?: ExportOptions | string): void;
+    /**
+     * 새 창을 열어 현재 그리드 데이터를 인쇄용 HTML 표로 렌더하고 인쇄 대화상자를 띄운다.
+     * / Opens a new window, renders the current grid data as a print-ready HTML table, and triggers the print dialog.
+     *
+     * 인쇄 문서의 `lang`·날짜 로케일·요약행 문구는 활성 로케일(`getMeta`/`t`)을 따른다
+     * (미주입 시 ko 폴백, byte-identical). / The document `lang`, date locale, and summary
+     * line follow the active locale (`getMeta`/`t`); falls back to ko when not injected (byte-identical).
+     *
+     * @param options - 제목·제외 필드·인쇄 푸터 텍스트 / Title, excluded fields, and print-footer text
+     */
     print(options?: {
         title?: string;
         excludeFields?: string[];
         footerText?: string;
     }): void;
+    /**
+     * 워크시트 매니저의 모든 시트를 시트별 탭으로 갖는 단일 `.xlsx` 로 내보낸다.
+     * / Export every sheet from the worksheet manager into a single `.xlsx` file, one tab per sheet.
+     *
+     * 워크시트 매니저가 없으면 {@link exportExcel} 로 폴백한다.
+     * / Falls back to {@link exportExcel} when no worksheet manager is present.
+     *
+     * @param filename - 파일명(확장자 생략 가능) / Output filename (extension optional)
+     */
     exportSheetsExcel(filename?: string): void;
 }

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

@@ -11,82 +11,228 @@ import { StrategySlot, StrategyMap, OverrideLayerFn, OverrideCallOptions, Overri
  * 3범주(§4.1): (a) strategy 슬롯(값·계산) · (b) 컴포넌트 registry(렌더훅 포함) · (c) lifecycle hook.
  * 이중구조(T-ζ): "SemVer 보증 카탈로그"(타입드 좁은 문) + "best-effort 임의 인터셉트 탈출구"(UC-11,
  * 넓은 문). 문서·타입에서 둘을 명확히 분리하되 넓은 문을 닫지 않는다.
+ * / R11 (§4 T3, §3.1 C7): a **typed extension-point registry** layered on top of the kernel.
+ *
+ * `OverrideKernel` is the execution engine (reversible, host-agnostic, zero source lines,
+ * untouchable — not a single line of it is modified). This registry is the **typed facade**
+ * placed on top of it, making the extension surface explicit, typed, and discoverable. The
+ * burden of extending the grid shifts from "editing core (adding a hardcoded gate)" to
+ * "registering data" (A4).
+ *
+ * Three categories (§4.1): (a) strategy slots (value/computation) · (b) component registries
+ * (including render hooks) · (c) lifecycle hooks. Dual structure (T-ζ): a "SemVer-guaranteed
+ * catalog" (the typed narrow door) plus a "best-effort arbitrary intercept escape hatch"
+ * (UC-11, the wide door). Docs and types keep the two clearly separated without ever closing
+ * the wide door.
  */
 /**
  * 렌더 참여 훅(§4.2). 렌더층이 셀마다 참조하는 교체가능 지점.
  *  - `gate()` : 미설정(등록 override/strategy 없음)이면 false → 렌더층이 resolve 를 호출조차 안 함(제로코스트).
  *  - `resolve(rowIndex, field)` : 게이트 통과 시 렌더층에 줄 값(표시문자열/클래스/aria 등). null=미참여.
  * 첫 등록 항목 = 기존 `getDisplayValue` 표시텍스트 동작(동일 출력 → 회귀0). 이후 새 훅은 등록만으로 열린다.
+ * / A render-participation hook (§4.2). A swappable point the render layer consults per cell.
+ *  - `gate()`: `false` when unconfigured (no override/strategy registered) — the render layer
+ *    won't even call `resolve` (zero cost).
+ *  - `resolve(rowIndex, field)`: the value to hand to the render layer once the gate passes
+ *    (display string/class/aria, etc.). `null` = does not participate.
+ * The first registered entry is the existing `getDisplayValue` display-text behavior (same
+ * output — zero regression). Any new hook opens up simply by registering.
  */
 export interface RenderHook<R = string> {
+    /** 훅 식별자(등록/조회 키). / Hook identifier (registration/lookup key). */
     readonly id: string;
+    /** 이 훅이 현재 활성인지. / Whether this hook is currently active. */
     gate(): boolean;
+    /** 게이트 통과 시의 셀 값 해석. / Resolve the cell value once the gate passes. */
     resolve(rowIndex: number, field: string): R | null;
 }
 /**
  * 렌더훅 레지스트리(§4.2). 하드코딩 게이트 1개를 데이터 구동 훅 목록으로 일반화.
  * 등록순 보존(첫 항목=표시텍스트). 렌더층은 이름을 하드코딩하지 않고 `resolve(id,…)` 로 순회 참조한다.
+ * / The render-hook registry (§4.2). Generalizes a single hardcoded gate into a
+ * data-driven list of hooks. Registration order is preserved (the first entry is the
+ * display-text hook). The render layer never hardcodes names — it consults hooks by
+ * iterating and calling `resolve(id, …)`.
  */
 export declare class RenderHookRegistry {
     private _order;
     private _hooks;
+    /**
+     * 훅을 등록한다(신규 id 는 등록순 끝에 추가, 기존 id 는 갱신). / Register a hook (a new id
+     * is appended to registration order; an existing id is updated in place).
+     *
+     * @param hook - 등록할 렌더훅 / The render hook to register
+     */
     register(hook: RenderHook<any>): void;
+    /**
+     * id 로 등록된 훅을 조회한다. / Look up a registered hook by id.
+     *
+     * @param id - 훅 식별자 / Hook identifier
+     * @returns 등록된 훅, 없으면 undefined / The registered hook, or `undefined`
+     */
     get(id: string): RenderHook<any> | undefined;
+    /**
+     * id 가 등록되어 있는지 확인한다. / Check whether an id is registered.
+     *
+     * @param id - 훅 식별자 / Hook identifier
+     * @returns 등록 여부 / Whether it is registered
+     */
     has(id: string): boolean;
-    /** 등록순 훅 id 목록(첫 항목=표시텍스트). */
+    /** 등록순 훅 id 목록(첫 항목=표시텍스트). / Registered hook ids in registration order (the first entry is display-text). */
     ids(): string[];
     /**
      * 훅 해석. 미등록이거나 게이트가 닫혀 있으면 resolve 를 **호출하지 않고** null 반환(제로코스트 보존).
+     * / Resolve a hook. If unregistered or its gate is closed, `resolve` is **not called** and
+     * `null` is returned (preserving zero cost).
+     *
+     * @param id - 훅 식별자 / Hook identifier
+     * @param rowIndex - 대상 행 인덱스 / Target row index
+     * @param field - 대상 컬럼 field 명 / Target column field name
+     * @returns 해석된 값, 미참여 시 null / The resolved value, or `null` if it does not participate
      */
     resolve(id: string, rowIndex: number, field: string): any;
-    /** 게이트가 열린(활성) 훅 id — 렌더층 스윕/디버깅용. */
+    /** 게이트가 열린(활성) 훅 id — 렌더층 스윕/디버깅용. / Ids of hooks whose gate is open (active) — for render-layer sweeps/debugging. */
     activeIds(): string[];
 }
-/** 단일 커밋 초크포인트(C5 MutationService)가 트리거로 감싸는 변경 연산. */
+/** 단일 커밋 초크포인트(C5 MutationService)가 트리거로 감싸는 변경 연산.
+ * / A mutation operation wrapped in a trigger by the single commit chokepoint (C5 MutationService). */
 export type MutationOp = 'setData' | 'insertRow' | 'deleteRow' | 'writeCell';
-/** 카탈로그(매니페스트) 엔트리 — R-3d "지원 확장점 카탈로그" 산출물. */
+/** 카탈로그(매니페스트) 엔트리 — R-3d "지원 확장점 카탈로그" 산출물.
+ * / A catalog (manifest) entry — the R-3d "supported extension point catalog" artifact. */
 export interface ExtensionCatalogEntry {
+    /** 확장점 이름. / Extension point name. */
     readonly name: string;
+    /** 확장점 범주. / Extension point category. */
     readonly category: 'strategy' | 'renderHook' | 'lifecycle' | 'override' | 'escapeHatch';
+    /** 사람이 읽는 시그니처 문자열. / Human-readable signature string. */
     readonly signature: string;
 }
+/**
+ * ExtensionPointRegistry 의 의존성 계약. / Dependency contract for ExtensionPointRegistry.
+ */
 export interface ExtensionRegistryDeps {
-    /** 실행 엔진(불가침). 레지스트리는 소유·위임할 뿐 내부를 건드리지 않는다. */
+    /** 실행 엔진(불가침). 레지스트리는 소유·위임할 뿐 내부를 건드리지 않는다.
+     * / The execution engine (untouchable). The registry only owns and delegates to it —
+     * it never reaches into its internals. */
     kernel: OverrideKernel;
-    /** before/after 취소가능 훅을 부착할 커밋 초크포인트의 TriggerManager(늦은-null 견딤). */
+    /** before/after 취소가능 훅을 부착할 커밋 초크포인트의 TriggerManager(늦은-null 견딤).
+     * / The commit chokepoint's TriggerManager, to which cancelable before/after hooks are
+     * attached (tolerates late-null). */
     getTrigMgr: () => TriggerManager;
 }
+/**
+ * R11 확장점 레지스트리. / R11 extension-point registry.
+ *
+ * `OverrideKernel` 실행 엔진 위에 얹는 타입드 정면으로, strategy 슬롯·렌더훅·lifecycle 훅·
+ * override 카탈로그를 하나의 등록 표면으로 노출한다(§4.1~§4.3).
+ * / The typed facade layered on top of the `OverrideKernel` execution engine, exposing
+ * strategy slots, render hooks, lifecycle hooks, and the override catalog as a single
+ * registration surface (§4.1–§4.3).
+ */
 export declare class ExtensionPointRegistry<T = any> {
     private _deps;
     private _renderHooks;
     constructor(deps: ExtensionRegistryDeps);
+    /** 렌더훅 레지스트리. / The render-hook registry. */
     get renderHooks(): RenderHookRegistry;
-    /** 렌더훅 등록(코어 편집 없이 렌더층 참여 지점 추가 — OCP). */
+    /**
+     * 렌더훅 등록(코어 편집 없이 렌더층 참여 지점 추가 — OCP).
+     * / Register a render hook (adds a render-layer participation point without editing
+     * core — OCP).
+     *
+     * @param hook - 등록할 렌더훅 / The render hook to register
+     * @example
+     * registry.registerRenderHook({
+     *   id: 'myBadge',
+     *   gate: () => true,
+     *   resolve: (rowIndex, field) => (field === 'status' ? 'badge-on' : null),
+     * });
+     */
     registerRenderHook(hook: RenderHook<any>): void;
-    /** 렌더층이 매 셀 호출 — 미등록/게이트닫힘이면 제로코스트 null. */
+    /**
+     * 렌더층이 매 셀 호출 — 미등록/게이트닫힘이면 제로코스트 null.
+     * / Called by the render layer for every cell — zero-cost `null` when unregistered or the
+     * gate is closed.
+     *
+     * @param id - 렌더훅 식별자 / Render hook identifier
+     * @param rowIndex - 대상 행 인덱스 / Target row index
+     * @param field - 대상 컬럼 field 명 / Target column field name
+     * @returns 해석된 값, 미참여 시 null / The resolved value, or `null` if it does not participate
+     */
     resolveRenderHook(id: string, rowIndex: number, field: string): any;
-    /** 타입드 슬롯 등록(SemVer 보증 카탈로그). 런타임은 커널 문자열 기반(하위호환). */
+    /**
+     * 타입드 슬롯 등록(SemVer 보증 카탈로그). 런타임은 커널 문자열 기반(하위호환).
+     * / Register a typed slot (SemVer-guaranteed catalog). At runtime it is still
+     * string-keyed via the kernel (backward compatible).
+     *
+     * @param slot - strategy 슬롯 이름 / Strategy slot name
+     * @param fn - 슬롯 구현 함수 / The slot implementation function
+     * @example
+     * registry.strategy('displayFormatter', (value, field, row) => String(value).toUpperCase());
+     */
     strategy<K extends StrategySlot>(slot: K, fn: StrategyMap[K]): void;
     strategy(slot: string, fn: Function): void;
-    /** 슬롯 조회(미등록 시 fallback — 매니저 read API, 제로코스트 철학 보존). */
+    /**
+     * 슬롯 조회(미등록 시 fallback — 매니저 read API, 제로코스트 철학 보존).
+     * / Look up a slot (falls back when unregistered — manager read API, preserving the
+     * zero-cost philosophy).
+     *
+     * @param slot - strategy 슬롯 이름 / Strategy slot name
+     * @param fallback - 미등록 시 사용할 기본 함수 / Default function used when unregistered
+     * @returns 등록된 함수 또는 fallback / The registered function, or the fallback
+     */
     getStrategy<F extends Function>(slot: string, fallback: F): F;
+    /**
+     * 슬롯 등록 여부를 확인한다. / Check whether a slot is registered.
+     *
+     * @param slot - strategy 슬롯 이름 / Strategy slot name
+     * @returns 등록 여부 / Whether it is registered
+     */
     hasStrategy(slot: string): boolean;
-    /** 타입드 오버로드: 좁은 "지원됨" 카탈로그(IDE 발견). */
+    /** 타입드 오버로드: 좁은 "지원됨" 카탈로그(IDE 발견). / Typed overload: the narrow "supported" catalog (IDE-discoverable). */
     override<K extends keyof OverridePoints<T>>(name: K, fn: OverrideLayerFn, opts?: OverrideCallOptions): void;
-    /** 탈출구(UC-11): 임의 메서드 best-effort 인터셉트 — 넓은 문은 닫지 않는다. */
+    /** 탈출구(UC-11): 임의 메서드 best-effort 인터셉트 — 넓은 문은 닫지 않는다. / Escape hatch (UC-11): best-effort intercept of an arbitrary method — the wide door stays open. */
     override(name: string, fn: OverrideLayerFn, opts?: OverrideCallOptions): void;
     /**
      * 취소가능 before 훅. 단일 커밋 초크포인트(C5 MutationService)가 이미 제공하는 `before:{op}`
      * 트리거를 **타입드로 표면화**할 뿐 메커니즘을 재배선하지 않는다. 핸들러가 `ctx.cancel()` 하면 변경 취소.
+     * / A cancelable before-hook. Merely **surfaces as typed** the `before:{op}` trigger already
+     * provided by the single commit chokepoint (C5 MutationService) — it does not rewire the
+     * mechanism. If the handler calls `ctx.cancel()`, the mutation is cancelled.
+     *
+     * @param op - 대상 변경 연산 / Target mutation operation
+     * @param handler - 취소 가능한 before 핸들러 / Cancelable before handler
+     * @example
+     * registry.beforeMutation('deleteRow', (ctx) => {
+     *   if (!confirm('삭제할까요?')) ctx.cancel();
+     * });
      */
     beforeMutation(op: MutationOp, handler: TriggerHandler): void;
-    /** 관찰(취소불가) after 훅 — 커밋 완료 후 `after:{op}` 트리거를 타입드로 표면화. */
+    /**
+     * 관찰(취소불가) after 훅 — 커밋 완료 후 `after:{op}` 트리거를 타입드로 표면화.
+     * / An observation-only (non-cancelable) after-hook — surfaces the `after:{op}` trigger,
+     * fired once the commit completes, as typed.
+     *
+     * @param op - 대상 변경 연산 / Target mutation operation
+     * @param handler - 관찰용 after 핸들러 / Observation-only after handler
+     */
     afterMutation(op: MutationOp, handler: TriggerHandler): void;
-    /** 등록한 MutationHook 해제. */
+    /**
+     * 등록한 MutationHook 해제. / Remove a previously registered MutationHook.
+     *
+     * @param when - 'before' 또는 'after' / `'before'` or `'after'`
+     * @param op - 대상 변경 연산 / Target mutation operation
+     * @param handler - 제거할 핸들러(등록 시와 동일 참조) / Handler to remove (same reference used at registration)
+     */
     offMutation(when: 'before' | 'after', op: MutationOp, handler: TriggerHandler): void;
     /**
      * 타입드 확장점 카탈로그. render 훅 항목은 실제 등록분(`renderHooks.ids()`)에서 유도 —
      * 유령 확장점(등록 없는 카탈로그 엔트리) 금지(DeMarco M9b).
+     * / The typed extension-point catalog. Render-hook entries are derived from the actual
+     * registrations (`renderHooks.ids()`) — no phantom extension points (catalog entries with
+     * no registration) are allowed (DeMarco M9b).
+     *
+     * @returns 확장점 카탈로그 엔트리 배열 / Array of extension-point catalog entries
      */
     catalog(): ExtensionCatalogEntry[];
 }

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

@@ -1,19 +1,37 @@
 import { FilterItem } from './types.js';
+/** 필터 적용 콜백. / Callback invoked when a filter is applied. */
 export type FilterApplyFn = (field: string, items: FilterItem[]) => void;
+/** 필터 해제 콜백. / Callback invoked when a filter is cleared. */
 export type FilterClearFn = (field: string) => void;
+/** i18n: 필터 라벨 로케일 해석기(주입 없으면 전역 t). / i18n: filter-label resolver (global t when not injected). */
+export type FilterPanelT = (key: string, params?: Record<string, string | number>) => string;
 /**
- * 컬럼 헤더 필터 드롭다운 패널.
- * 단일 인스턴스를 재사용(열릴 때 위치 재계산).
+ * 컬럼 헤더 필터 드롭다운 패널. / Column-header filter dropdown panel.
+ *
+ * 단일 인스턴스를 재사용하며, 열릴 때마다 대상 컬럼(`field`)과 앵커 기준 위치를
+ * 재계산한다. / Reuses a single instance; on each open it recomputes the target
+ * column (`field`) and its anchor-relative position.
  */
 export declare class FilterPanel {
     private _el;
     private _field;
     private _onApply;
     private _onClear;
+    private _t;
     private _outsideHandler;
-    constructor(container: HTMLElement, onApply: FilterApplyFn, onClear: FilterClearFn);
+    constructor(container: HTMLElement, onApply: FilterApplyFn, onClear: FilterClearFn, t?: FilterPanelT);
+    /**
+     * 지정 컬럼의 필터 패널을 앵커 엘리먼트 아래에 연다. / Open the filter panel for the given column, anchored below `anchorEl`.
+     *
+     * @param field - 필터 대상 컬럼 field 명 / Field name of the column to filter
+     * @param anchorEl - 위치 기준이 되는 헤더 엘리먼트(보통 필터 아이콘) / Header element used as the position anchor (typically the filter icon)
+     * @param currentFilters - 해당 컬럼에 이미 적용된 필터(있으면 입력값 프리필) / Filters already applied to this column (pre-fills the inputs, if any)
+     */
     open(field: string, anchorEl: HTMLElement, currentFilters: FilterItem[]): void;
+    /** 필터 패널을 숨기고 외부 클릭 리스너를 해제한다. / Hide the filter panel and detach the outside-click listener. */
     close(): void;
+    /** 패널이 현재 열려 있는지 여부. / Whether the panel is currently open. */
     get isOpen(): boolean;
+    /** 패널을 닫고 DOM 에서 제거한다. / Close the panel and remove it from the DOM. */
     destroy(): void;
 }