open-grid 1.2.0 → 1.2.1

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

@@ -29,6 +29,14 @@ import { GridOptions } from './types.js';
  * 조립 중 대입·참조하는 대상이며, 잘못된 이름/타입의 대입은 이 인터페이스로 인해 컴파일
  * 타임에 잡힌다(순수 `any` host 보다 안전). `_mount` 본체(renderer/vs/pagination 등 DOM
  * 배선)는 여전히 OpenGrid 가 소유하며, 컴포저는 mount 단계에서 `_mount()` 를 호출만 한다.
+ * / The internal surface of `OpenGrid` that `GridComposer` accesses while assembling it
+ * (R8, §3.1 C2, §3.3).
+ *
+ * Structurally mirrors `OpenGrid`'s private fields/methods. Only the members enumerated here
+ * are ones the composer assigns to or reads during assembly; assigning a wrong name/type is
+ * caught at compile time thanks to this interface (safer than a plain `any` host). The body of
+ * `_mount` (renderer/vs/pagination DOM wiring, etc.) is still owned by `OpenGrid` — the
+ * composer only calls `_mount()` at the mount phase.
  */
 export interface ComposerHost<T extends Record<string, any> = any> {
     _container: HTMLElement;
@@ -51,7 +59,9 @@ export interface ComposerHost<T extends Record<string, any> = any> {
     _detailMgr: DetailManager<T>;
     _chartMgr: ChartManager;
     _ovk: OverrideKernel;
-    /** i18n: per-instance 로케일 오버라이드 child(전역 localeRegistry 의 child). 미지정 시 null → 전역 직행. */
+    /** i18n: per-instance 로케일 오버라이드 child(전역 localeRegistry 의 child). 미지정 시 null → 전역 직행.
+     * / i18n: per-instance locale-override child (a child of the global localeRegistry).
+     * `null` when unspecified, in which case lookups go straight to the global registry. */
     _locales: LocaleRegistry | null;
     _renderer: GridRenderer | null;
     _vs: VirtualScroll | null;
@@ -62,8 +72,9 @@ export interface ComposerHost<T extends Record<string, any> = any> {
     emit(event: string, ...args: any[]): any;
     on(event: string, cb: (...args: any[]) => void): any;
     off(event: string, cb: (...args: any[]) => void): any;
+    /** aria-live announce. */
     _announce(msg: string): void;
-    /** i18n: 메시지 해석(인스턴스 오버라이드 우선 → 활성 로케일 → ko → 키). / i18n: resolve a message. */
+    /** i18n: 메시지 해석(인스턴스 오버라이드 우선 → 활성 로케일 → ko → 키). / i18n: resolve a message (instance override first, then active locale, then ko, then the raw key). */
     t(key: string, params?: Record<string, string | number>): string;
     _doRender(startIndex: number, endIndex: number): void;
     _visRange(): [number, number];
@@ -83,30 +94,46 @@ export interface ComposerHost<T extends Record<string, any> = any> {
     getCellFormula(rowIndex: number, field: string): string | null;
     setCellFormula(rowIndex: number, field: string, formula: string): void;
     clearCellFormula(rowIndex: number, field: string): void;
-    /** override 커널 배선 후 컴포저가 단 1회 호출(구조적 순서 관문). */
+    /** override 커널 배선 후 컴포저가 단 1회 호출(구조적 순서 관문). / Called exactly once by the composer after the override kernel is wired up (a structural ordering gate). */
     _mount(): void;
 }
-/** OpenGrid 만 알아야 하는 재귀/전역 배선을 컴포저에 주입(컴포저의 OpenGrid 역-import 회피). */
+/** OpenGrid 만 알아야 하는 재귀/전역 배선을 컴포저에 주입(컴포저의 OpenGrid 역-import 회피).
+ * / Injects into the composer the recursive/global wiring that only `OpenGrid` needs to know
+ * about (avoids the composer having to reverse-import `OpenGrid`). */
 export interface ComposerHooks {
-    /** F2 서브그리드 재귀 생성(DetailManager createSubgrid). `new OpenGrid(host, {..,_detailDepth})`. */
+    /** F2 서브그리드 재귀 생성(DetailManager createSubgrid). `new OpenGrid(host, {..,_detailDepth})`.
+     * / F2: recursively create a subgrid (DetailManager's createSubgrid) — `new OpenGrid(host, {..,_detailDepth})`.
+     *
+     * @param host - 서브그리드를 마운트할 컨테이너 엘리먼트 / Container element to mount the subgrid into
+     * @param subgridOptions - 서브그리드 생성 옵션 / Subgrid construction options
+     * @param depth - 중첩 깊이(재귀 가드) / Nesting depth (recursion guard)
+     * @returns 생성된 서브그리드 인스턴스 / The created subgrid instance
+     */
     createSubgrid: (host: HTMLElement, subgridOptions: any, depth: number) => any;
 }
+/** Phase A(core) 완료 토큰. / Completion token for Phase A (core). */
 export interface CoreServicesToken {
     readonly _phase: 'core';
 }
+/** Phase B(formula) 완료 토큰. / Completion token for Phase B (formula). */
 export interface FormulaServicesToken {
     readonly _phase: 'formula';
 }
+/** Phase C(managers) 완료 토큰. / Completion token for Phase C (managers). */
 export interface ManagerRegistryToken {
     readonly _phase: 'managers';
 }
+/** Phase D(override kernel) 완료 토큰. / Completion token for Phase D (override kernel). */
 export interface OverrideKernelToken {
     readonly _phase: 'ovk';
 }
+/** Phase E(mount) 완료 토큰. / Completion token for Phase E (mount). */
 export interface MountedViewToken {
     readonly _phase: 'mounted';
 }
-/** compose() 산출물 핸들. 모든 협력자는 host 에 대입되며, 이 핸들은 완료 표식이다. */
+/** compose() 산출물 핸들. 모든 협력자는 host 에 대입되며, 이 핸들은 완료 표식이다.
+ * / The handle produced by compose(). All collaborators are assigned onto the host; this
+ * handle is merely a completion marker. */
 export interface GridRuntime {
     readonly mounted: MountedViewToken;
 }
@@ -120,8 +147,29 @@ export interface GridRuntime {
  *
  * 협력자 생성 순서는 기존 생성자와 바이트 동일(회귀0): core → formula/recalc → 11 매니저
  * → override 커널 → mount. R2 런타임 가드는 belt-and-suspenders 로 유지된다.
+ * / The composition root / phased builder (R8, §6-R8, §3.1 C2, §3.3).
+ *
+ * Externalizes the object-graph assembly that used to be fused into the constructor. Each
+ * `build*` phase requires the previous phase's output token as a parameter, so construction
+ * order — in particular the invariant that `_ovk` (OverrideKernel) must be created before
+ * `_mount()` — is enforced by **topologically sorting the function signatures**: `mount(ovk)`
+ * simply does not compile without the token produced by `buildOverrideKernel()`.
+ *
+ * Collaborator creation order is byte-identical to the original constructor (zero regression):
+ * core → formula/recalc → 11 managers → override kernel → mount. The R2 runtime guard is kept
+ * as a belt-and-suspenders check.
  */
 export declare class GridComposer {
+    /**
+     * 그리드 객체그래프를 전 단계 순서대로 조립하고 mount 한다. / Assemble the grid's object
+     * graph through every phase, in order, and mount it.
+     *
+     * @param host - 조립 대상 OpenGrid 내부 표면 / The OpenGrid internal surface to assemble into
+     * @param container - 컨테이너 셀렉터 또는 엘리먼트 / Container selector or element
+     * @param rawOptions - 사용자 지정 그리드 옵션(정규화 전) / User-supplied grid options (pre-normalization)
+     * @param hooks - OpenGrid 전용 재귀/전역 배선 훅 / OpenGrid-only recursive/global wiring hooks
+     * @returns compose 완료 핸들 / The completion handle for compose
+     */
     static compose<T extends Record<string, any>>(host: ComposerHost<T>, container: string | HTMLElement, rawOptions: GridOptions<T>, hooks: ComposerHooks): GridRuntime;
     /** Phase A: 컨테이너 해석 + 옵션 정규화 + 코어 서비스(DataLayer/FlatRowModel/RowManager/ColumnLayout). */
     private static buildCoreServices;

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

@@ -1,10 +1,15 @@
 import { OpenGridInstance } from './types.js';
+/**
+ * 그리드 셔틀 생성 옵션. / Grid shuttle construction options.
+ */
 export interface GridShuttleOptions {
-    /** 버튼 배치 방향 (기본 'vertical') */
+    /** 버튼 배치 방향. 기본 'vertical'. / Button layout direction. Default 'vertical'.
+     *  @defaultValue 'vertical' */
     layout?: 'vertical' | 'horizontal';
-    /** 전체 이동(≫ ≪) 버튼도 표시 (기본 false) */
+    /** 전체 이동(≫ ≪) 버튼도 표시. 기본 false. / Also show move-all (≫ ≪) buttons. Default false.
+     *  @defaultValue false */
     includeAll?: boolean;
-    /** 버튼 라벨 커스터마이즈 */
+    /** 버튼 라벨 커스터마이즈. / Customize button labels. */
     labels?: {
         toRight?: string;
         toLeft?: string;
@@ -12,13 +17,48 @@ export interface GridShuttleOptions {
         allLeft?: string;
     };
 }
+/**
+ * 두 그리드 사이의 셔틀 UI. / Shuttle UI between two grids.
+ *
+ * 두 그리드 사이에 화살표 버튼을 두고 "체크된 행"을 드래그 없이 버튼으로 이동(move)시킨다.
+ * 이동은 `grid.moveCheckedTo()` 를 호출하므로 crossGridMapping(필드 매핑)과 3단계 이벤트가
+ * 드래그 이동과 100% 동일하게 적용된다.
+ * / Places arrow buttons between two grids to move "checked rows" without dragging.
+ * The move delegates to `grid.moveCheckedTo()`, so crossGridMapping (field mapping) and the
+ * 3-stage events apply identically to drag-based moves.
+ *
+ * @example
+ * const shuttle = new GridShuttle(leftGrid, rightGrid, document.querySelector('#mid')!, {
+ *   layout: 'vertical',
+ *   includeAll: true,
+ * });
+ */
 export declare class GridShuttle {
     private _left;
     private _right;
     private _el;
+    /**
+     * @param _left - 왼쪽 그리드 인스턴스 / Left grid instance
+     * @param _right - 오른쪽 그리드 인스턴스 / Right grid instance
+     * @param mount - 셔틀 버튼을 붙일 마운트 엘리먼트 / Mount element to attach the shuttle buttons
+     * @param opts - 셔틀 옵션 / Shuttle options
+     */
     constructor(_left: OpenGridInstance, _right: OpenGridInstance, mount: HTMLElement, opts?: GridShuttleOptions);
     private _moveAll;
+    /** 셔틀 UI 를 DOM 에서 제거한다. / Remove the shuttle UI from the DOM. */
     destroy(): void;
 }
-/** 두 그리드 사이에 셔틀(화살표 이동) 버튼을 만든다 */
+/**
+ * 두 그리드 사이에 셔틀(화살표 이동) 버튼을 만든다. / Create shuttle (arrow-move) buttons between two grids.
+ *
+ * `new GridShuttle(...)` 의 편의 팩토리. / Convenience factory for `new GridShuttle(...)`.
+ *
+ * @param left - 왼쪽 그리드 인스턴스 / Left grid instance
+ * @param right - 오른쪽 그리드 인스턴스 / Right grid instance
+ * @param mount - 셔틀 버튼을 붙일 마운트 엘리먼트 / Mount element to attach the shuttle buttons
+ * @param opts - 셔틀 옵션 / Shuttle options
+ * @returns 생성된 GridShuttle 인스턴스 / The created GridShuttle instance
+ * @example
+ * const shuttle = createGridShuttle(leftGrid, rightGrid, mountEl, { includeAll: true });
+ */
 export declare function createGridShuttle(left: OpenGridInstance, right: OpenGridInstance, mount: HTMLElement, opts?: GridShuttleOptions): GridShuttle;

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

@@ -2,18 +2,37 @@ import { DataLayer } from './DataLayer.js';
 import { VirtualScroll } from './VirtualScroll.js';
 import { GroupRow } from './GroupEngine.js';
 import { TreeNode } from './TreeEngine.js';
+/**
+ * {@link GroupTreeManager} 의존성 주입 계약. / Dependency-injection contract for {@link GroupTreeManager}.
+ *
+ * 그룹/트리 재구성에 필요한 데이터·렌더·백킹 배선 훅을 호스트 그리드가 제공한다.
+ * / The host grid supplies the data/render/backing-wiring hooks needed to rebuild
+ * groups and trees.
+ */
 export interface GroupTreeDeps<T extends Record<string, any>> {
+    /** 현재 원본 행 배열 조회. / Look up the current raw row array. */
     getData: () => T[];
+    /** 현재 데이터 레이어 조회. / Look up the current data layer. */
     getDataLayer: () => DataLayer<T>;
+    /** 현재 그리드 옵션 조회. / Look up the current grid options. */
     getOptions: () => any;
+    /** 가상 스크롤 인스턴스 조회(없으면 `null`). / Look up the virtual-scroll instance (or `null`). */
     getVs: () => VirtualScroll | null;
+    /** 전체 재계산 렌더(총 행수 갱신 포함). / Full re-render including a total-row-count refresh. */
     doRenderFull: (totalRows: number) => void;
+    /** 바디를 다시 그린다. / Re-render the body. */
     doRender: () => void;
-    /** Phase 2: OverrideKernel.getStrategy 주입(슬롯 groupKeyFn 도달용). */
+    /** Phase 2: OverrideKernel.getStrategy 주입(슬롯 groupKeyFn 도달용).
+     * / Phase 2: injected `OverrideKernel.getStrategy` (reaches the `groupKeyFn` slot). */
     getStrategy?: <F extends Function>(slot: string, fallback: F) => F;
     /**
      * Phase 0(C0.3): FlatRowModel 의 baseline backing 등록점. group/tree 진입 시 자기
      * flat 배열(`_groupFlatRows`/`_treeFlatRows`)로 교체하고, 해제 시 null(plain 복귀)로 되돌린다.
+     * / Phase 0 (C0.3): registration point for `FlatRowModel`'s baseline backing. Swapped
+     * to this manager's own flat array (`_groupFlatRows`/`_treeFlatRows`) on entering
+     * group/tree mode, and reset to `null` (plain mode) on exit.
+     *
+     * @param provider - flat 행 배열을 반환하는 함수, 해제 시 `null` / Function returning the flat row array, or `null` to detach
      */
     setFlatBacking: (provider: (() => Array<any>) | null) => void;
     /**
@@ -22,9 +41,27 @@ export interface GroupTreeDeps<T extends Record<string, any>> {
      * backing 위에 DetailManager 가 등록한 detail splice 까지 합성한 "최종" 총 행수이므로,
      * GroupTreeManager 는 자기 배열 길이(`_groupFlatRows.length` 등)를 직접 쓰지 않는다
      * (detail 활성 시 그 값은 실제보다 작아 스크롤/렌더 범위가 잘린다).
+     * / F2 (11_design_F2_v2.md §3.2 R3, resolving the "flat ownership contention" issue):
+     * queried right after `setFlatBacking` and passed to `VirtualScroll.setTotalRows`/
+     * `doRenderFull`. `FlatRowModel.count()` is the "final" total row count — it composites
+     * the backing just swapped in with any detail splices `DetailManager` has registered —
+     * so `GroupTreeManager` never uses its own array length (`_groupFlatRows.length`, etc.)
+     * directly (with detail active, that length is smaller than the real total and would
+     * truncate the scroll/render range).
+     *
+     * @returns 합성된 최종 총 행수 / The composited final total row count
      */
     getFlatCount: () => number;
 }
+/**
+ * 그룹핑과 트리 모드를 함께 관리하는 매니저. / Manages both grouping and tree (parent/child) modes.
+ *
+ * 그룹/트리는 상호 배타적이며, 둘 다 원본 데이터를 하나의 "flat 배열"로 펼쳐
+ * {@link GroupTreeDeps.setFlatBacking} 을 통해 가상 스크롤의 백킹으로 등록한다.
+ * / Grouping and tree mode are mutually exclusive; both flatten the source data into
+ * a single "flat array" and register it as the virtual-scroll backing via
+ * {@link GroupTreeDeps.setFlatBacking}.
+ */
 export declare class GroupTreeManager<T extends Record<string, any> = any> {
     private _groupFields;
     private _groupExpandedKeys;
@@ -36,24 +73,71 @@ export declare class GroupTreeManager<T extends Record<string, any> = any> {
     private _isTreeMode;
     private _d;
     constructor(deps: GroupTreeDeps<T>);
+    /** 그룹 모드 활성 여부. / Whether group mode is active. */
     get isGroupMode(): boolean;
+    /** 트리 모드 활성 여부. / Whether tree mode is active. */
     get isTreeMode(): boolean;
+    /** 현재 펼쳐진 그룹 flat 행 배열(그룹 헤더/요약/데이터 행 혼합). / Current flattened group rows (mix of group header/summary/data rows). */
     get groupFlatRows(): Array<GroupRow<T> | T>;
+    /** 현재 펼쳐진 트리 flat 노드 배열(펼침 상태 반영). / Current flattened tree nodes (reflects expand/collapse state). */
     get treeFlatRows(): TreeNode<T>[];
+    /**
+     * 지정 필드로 그룹핑을 시작(또는 재설정)한다. / Start (or reset) grouping by the given fields.
+     *
+     * @param fields - 그룹 기준 필드명 배열(순서대로 중첩). 빈 배열이면 그룹 해제 / Fields to group by, in nesting order; an empty array disables grouping
+     */
     groupBy(fields: string[]): void;
+    /** 그룹핑을 해제하고 평면 모드로 복귀한다. / Disable grouping and return to flat mode. */
     clearGroup(): void;
+    /** 모든 그룹을 펼친다(그룹 모드가 아니면 무시). / Expand every group (no-op outside group mode). */
     expandAll(): void;
-    /** Phase 2 슬롯 #5: groupKeyFn resolver. default = undefined(→ GroupEngine 가 row[field] 사용). */
+    /** Phase 2 슬롯 #5: groupKeyFn resolver. default = undefined(→ GroupEngine 가 row[field] 사용).
+     * / Phase 2 slot #5: groupKeyFn resolver. Default `undefined` (falls back to
+     * `GroupEngine` using `row[field]`).
+     * @internal */
     private _groupKeyFn;
+    /** 모든 그룹을 접는다. / Collapse every group. */
     collapseAll(): void;
+    /**
+     * 특정 그룹의 펼침/접힘을 토글한다. / Toggle a single group's expand/collapse state.
+     *
+     * @param groupKey - 대상 그룹의 키 / Key of the target group
+     */
     handleGroupToggle(groupKey: string): void;
+    /**
+     * 현재 그룹 필드/펼침 상태로 flat 행 배열을 재계산하고 렌더한다. / Recompute the flat row array from the current group fields/expand state and render.
+     */
     rebuildGroups(): void;
+    /**
+     * 트리 모드를 활성화한다(그룹 모드와 배타). / Enable tree mode (mutually exclusive with group mode).
+     *
+     * `expandOnLoad` 옵션이 켜져 있으면 전체 노드를 펼친 상태로 시작한다.
+     * / If the `expandOnLoad` option is on, starts with every node expanded.
+     */
     enableTree(): void;
+    /** 트리 모드를 해제하고 평면 모드로 복귀한다. / Disable tree mode and return to flat mode. */
     disableTree(): void;
+    /**
+     * 지정 노드(들)를 펼치거나 접는다. / Expand or collapse the given node(s).
+     *
+     * @param ids - 대상 노드 id, 또는 id 배열 / A single node id, or an array of node ids
+     * @param open - `true` 면 펼침, `false` 면 접힘(기본 `true`) / `true` to expand, `false` to collapse (default `true`)
+     */
     expandNodes(ids: any | any[], open?: boolean): void;
+    /** 모든 트리 노드를 펼친다(트리 모드가 아니면 무시). / Expand every tree node (no-op outside tree mode). */
     expandAllNodes(): void;
+    /** 모든 트리 노드를 접는다(트리 모드가 아니면 무시). / Collapse every tree node (no-op outside tree mode). */
     collapseAllNodes(): void;
+    /**
+     * 특정 트리 노드의 펼침/접힘을 토글한다. / Toggle a single tree node's expand/collapse state.
+     *
+     * @param nodeId - 대상 노드 id / Id of the target node
+     */
     handleTreeToggle(nodeId: any): void;
+    /**
+     * 현재 펼침 상태로 트리를 재구성하고 flat 행 배열을 갱신한다. / Rebuild the tree from the current expand state and refresh the flat row array.
+     */
     rebuildTree(): void;
+    /** @internal */
     private _getSummaryDefs;
 }

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

@@ -1,25 +1,40 @@
-/** render() 옵션. size 미지정 시 svg 는 viewBox/CSS 로 크기를 상속(width/height 속성 생략). */
+/**
+ * render() 옵션. size 미지정 시 svg 는 viewBox/CSS 로 크기를 상속(width/height 속성 생략).
+ * / render() options. When size is omitted, the svg inherits its size from viewBox/CSS (width/height attrs skipped).
+ */
 export interface IconRenderOptions {
-    /** px 정사각 크기(width=height). 미지정 시 속성 생략(CSS/컨테이너가 결정). */
+    /** px 정사각 크기(width=height). 미지정 시 속성 생략(CSS/컨테이너가 결정). / Square size in px (width=height); omitted when unset (CSS/container decides). */
     size?: number;
-    /** 접근성 제목. 지정 시 <title> + role="img" 추가(스크린리더). 미지정 시 장식용(부모가 aria 담당). */
+    /** 접근성 제목. 지정 시 <title> + role="img" 추가(스크린리더). 미지정 시 장식용(부모가 aria 담당). / Accessible title; adds <title> + role="img" when set (screen readers). Decorative otherwise (parent owns aria). */
     title?: string;
-    /** true → SVGElement(DOMParser) 반환. 기본 false → SVG 마크업 문자열. */
+    /** true → SVGElement(DOMParser) 반환. 기본 false → SVG 마크업 문자열. / true → return an SVGElement (DOMParser). Default false → SVG markup string. @defaultValue false */
     el?: boolean;
 }
 /**
  * 시맨틱 ROLE → 아이콘 key(`BOOTSTRAP_ICONS` 의 symbolId) 기본 매핑.
+ * / Default map of semantic ROLE → icon key (a `BOOTSTRAP_ICONS` symbolId).
+ *
  * 렌더 코드는 이 역할 이름만 참조한다. key 교체는 이 표(혹은 register/setIcon)만 고치면 된다.
  * 참고 스왑: `row.delete`→`trash3`(Bootstrap 의 표준 휴지통, task 의 'trash' 동족), `chart.line`→`graph-up`.
+ * / Render code references only these role names; swapping a glyph means editing this table (or register/setIcon).
  */
 export declare const DEFAULT_ICON_ROLES: Readonly<Record<string, string>>;
 /**
  * IconRegistry — role → 글리프 본문(inner SVG markup) 해석 + svg 래핑.
+ * / IconRegistry — resolves role → glyph body (inner SVG markup) and wraps it in an svg.
  *
  * 저장 단위는 **글리프 본문 문자열**(<path>/<g> 마크업). register(role, svgOrKey) 는
  *   - svgOrKey 가 `BOOTSTRAP_ICONS` 의 알려진 key 면 그 본문으로,
  *   - 아니면 **원시 SVG 본문**(사용자 커스텀 <path…>)으로 저장한다.
  * 부모 체인(_parent)으로 per-instance 오버라이드 레지스트리를 전역 위에 얹는다(멀티그리드 격리).
+ * / The storage unit is the glyph body string (<path>/<g> markup). register(role, svgOrKey) stores either
+ * the body of a known `BOOTSTRAP_ICONS` key, or the raw SVG body otherwise. A parent chain (_parent) layers
+ * a per-instance override registry on top of the global one (multi-grid isolation).
+ *
+ * @example
+ * const reg = iconRegistry.child();
+ * reg.register('sort.asc', 'arrow-up');
+ * const svg = reg.render('sort.asc', { size: 16 }) as string;
  */
 export declare class IconRegistry {
     private _roles;
@@ -28,28 +43,60 @@ export declare class IconRegistry {
     /**
      * role 에 글리프를 등록/교체. svgOrKey 가 알려진 아이콘 key 면 그 본문을, 아니면 원시 SVG
      * 본문 마크업으로 간주한다(코어 편집 없이 아이콘 교체 — OCP).
+     * / Register/replace a glyph for a role. A known icon key resolves to its body; otherwise svgOrKey is
+     * treated as raw SVG body markup (swap icons without editing core — OCP).
+     *
+     * @param role - 시맨틱 역할 키(예: 'sort.asc') / Semantic role key (e.g. 'sort.asc')
+     * @param svgOrKey - 알려진 아이콘 key 또는 원시 SVG 본문 / A known icon key or raw SVG body
+     * @returns 체이닝용 this / this for chaining
      */
     register(role: string, svgOrKey: string): this;
-    /** role 이 (자신 또는 부모 체인에) 등록돼 있는가. */
+    /** role 이 (자신 또는 부모 체인에) 등록돼 있는가. / Whether a role is registered (self or parent chain). */
     has(role: string): boolean;
-    /** role → 글리프 본문(inner markup). 미등록이면 null(부모 체인까지 조회). */
+    /**
+     * role → 글리프 본문(inner markup). 미등록이면 null(부모 체인까지 조회).
+     * / role → glyph body (inner markup); null if unregistered (searches up the parent chain).
+     *
+     * @param role - 조회할 역할 키 / Role key to resolve
+     * @returns 글리프 본문 또는 null / Glyph body or null
+     */
     resolveBody(role: string): string | null;
-    /** 이 레지스트리를 부모로 하는 자식(per-instance 오버라이드용) 생성. */
+    /** 이 레지스트리를 부모로 하는 자식(per-instance 오버라이드용) 생성. / Create a child registry with this as parent (for per-instance overrides). */
     child(): IconRegistry;
     /**
      * role 을 `<svg viewBox=ICON_VIEWBOX>` 로 렌더. 기본 반환은 SVG 마크업 문자열(innerHTML 용);
      * opts.el 이면 SVGElement. 미지원 role 은 빈 svg 폴백(never throw).
      * 스킨 토큰: fill=currentColor(presentation attr) + stroke-linejoin=var(--og-icon-corner,miter).
+     * / Render a role as `<svg viewBox=ICON_VIEWBOX>`. Returns SVG markup string by default (for innerHTML);
+     * opts.el returns an SVGElement. Unknown roles fall back to an empty svg (never throws).
+     *
+     * @param role - 렌더할 역할 키 / Role key to render
+     * @param opts - 렌더 옵션 / Render options
+     * @returns SVG 마크업 문자열 또는 SVGElement(opts.el) / SVG markup string, or SVGElement when opts.el
      */
     render(role: string, opts?: IconRenderOptions): string | SVGElement;
-    /** 등록된 role 목록(자신만, 디버깅/테스트용). */
+    /** 등록된 role 목록(자신만, 디버깅/테스트용). / List of registered roles (self only; for debugging/tests). */
     roles(): string[];
 }
 /**
  * 프로세스 공유 기본 아이콘 레지스트리(시맨틱 role 시드 완료).
+ * / Process-shared default icon registry (seeded with semantic roles).
+ *
  * CellRenderer 등 팩토리 생성 렌더러(인스턴스 컨텍스트 없음)가 이 초크포인트로 아이콘을 얻는다.
  * per-instance 교체는 `grid.setIcon()`(이 레지스트리의 child) 로, 전역 확장은 `defineIconSet()` 로.
+ * / Factory-created renderers (e.g. CellRenderer, without instance context) obtain icons through this
+ * chokepoint. Per-instance swaps go through `grid.setIcon()` (a child of this registry); global extension
+ * through `defineIconSet()`.
  */
 export declare const iconRegistry: IconRegistry;
-/** 편의 정적 render — 공유 기본 레지스트리로 위임(`IconRegistry.render(role, opts)`). */
+/**
+ * 편의 정적 render — 공유 기본 레지스트리로 위임(`IconRegistry.render(role, opts)`).
+ * / Convenience static render — delegates to the shared default registry (`IconRegistry.render(role, opts)`).
+ *
+ * @param role - 렌더할 역할 키 / Role key to render
+ * @param opts - 렌더 옵션 / Render options
+ * @returns SVG 마크업 문자열 또는 SVGElement(opts.el) / SVG markup string, or SVGElement when opts.el
+ * @example
+ * el.innerHTML = renderIcon('filter') as string;
+ */
 export declare function renderIcon(role: string, opts?: IconRenderOptions): string | SVGElement;

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

@@ -2,45 +2,129 @@ import { DataLayer } from './DataLayer.js';
 import { ColumnLayout } from './ColumnLayout.js';
 import { CellEditManager } from './CellEditManager.js';
 import { RowManager } from './RowManager.js';
-/** F1 범위 선택 배선 훅(M-3/M-4/M-5) — RangeSelectionManager 가 그대로 구현한다. */
+/**
+ * F1 범위 선택 배선 훅(M-3/M-4/M-5) — RangeSelectionManager 가 그대로 구현한다.
+ * / F1 range-selection wiring hooks (M-3/M-4/M-5) — implemented directly by
+ * `RangeSelectionManager`.
+ */
 export interface RangeKeyboardHooks {
+    /** 범위 선택 모드(`selection:'cells'`)가 활성인지. / Whether range-select mode (`selection:'cells'`) is active. */
     isEnabled(): boolean;
+    /** 현재 유효한 범위 선택이 있는지. / Whether there is a currently valid range selection. */
     hasSelection(): boolean;
+    /**
+     * 포커스를 지정 방향으로 확장한다(Shift+화살표). / Extend the focus range in the given direction (Shift+Arrow).
+     * @param dir - 확장 방향 / Direction to extend
+     */
     extendFocus(dir: 'up' | 'down' | 'left' | 'right'): void;
+    /**
+     * Ctrl+D/Ctrl+R 채우기를 축 방향으로 실행한다. / Run a Ctrl+D/Ctrl+R fill along the given axis.
+     * @param axis - 채우기 축(`'down'` = Ctrl+D, `'right'` = Ctrl+R) / Fill axis (`'down'` for Ctrl+D, `'right'` for Ctrl+R)
+     */
     ctrlFill(axis: 'down' | 'right'): void;
+    /** 범위 선택을 해제한다. / Clear the range selection. */
     clear(): void;
-    /** 범위 없으면 null(호출측이 기존 focusCell/selectedRows 경로로 폴백) */
+    /**
+     * 범위 없으면 null(호출측이 기존 focusCell/selectedRows 경로로 폴백)
+     * / Returns `null` when there is no range (caller falls back to the
+     * focusCell/selectedRows path).
+     * @returns 범위의 TSV 텍스트, 또는 `null` / TSV text of the range, or `null`
+     */
     copyText(): string | null;
-    /** true = 배치 경유로 처리함, false = 범위 없음(폴백) */
+    /**
+     * true = 배치 경유로 처리함, false = 범위 없음(폴백)
+     * / `true` if handled via the batch path, `false` if there is no range (caller falls back).
+     * @param text - 붙여넣을 TSV 텍스트 / TSV text to paste
+     * @returns 배치 경유로 처리되었는지 여부 / Whether this was handled via the batch path
+     */
     pasteText(text: string): boolean;
 }
+/**
+ * {@link KeyboardManager} 의존성 주입 계약. / Dependency-injection contract for {@link KeyboardManager}.
+ */
 export interface KeyboardDeps<T extends Record<string, any>> {
+    /** 셀 편집 매니저 조회. / Look up the cell edit manager. */
     getEditMgr: () => CellEditManager<T>;
+    /** 행 선택/체크 매니저 조회. / Look up the row selection/check manager. */
     getRowMgr: () => RowManager<T>;
+    /** 현재 데이터 레이어 조회. / Look up the current data layer. */
     getData: () => DataLayer<T>;
+    /** 현재 컬럼 레이아웃 조회. / Look up the current column layout. */
     getColLayout: () => ColumnLayout<T>;
+    /** 현재 그리드 옵션 조회. / Look up the current grid options. */
     getOptions: () => any;
+    /** 키보드 포커스 셀을 설정한다. / Set the keyboard-focused cell. */
     setFocusCell: (ri: number, ci: number) => void;
+    /** 행 드래그(Ctrl+화살표) 이동을 처리한다. / Handle a row drag (Ctrl+Arrow) move. */
     handleRowDrop: (from: number, to: number) => void;
+    /** 바디를 다시 그린다. / Re-render the body. */
     doRender: () => void;
+    /** 스크린리더용 상태 안내. / Announce a status message for screen readers. */
     announce: (msg: string) => void;
     /** i18n: 행 이동 announce 해석. / i18n: resolve row-move announce. */
     t: (key: string, params?: Record<string, string | number>) => string;
+    /** 그리드 이벤트를 발행한다. / Emit a grid event. */
     emit: (event: string, ...args: any[]) => void;
+    /** 현재 렌더된 가시 행 범위(`[start, end]`)를 조회. / Look up the currently rendered visible row range (`[start, end]`). */
     visRange: () => [number, number];
+    /** 포커스 셀에 대한 공개 키 이벤트를 발행한다. / Emit a public key event for the focused cell. */
     handleCellKeyEvt: (eventName: 'cellKeyDown' | 'cellKeyUp' | 'cellKeyPress', e: KeyboardEvent) => void;
-    /** M-4: 붙여넣기 쓰기 퍼널을 writeCell(배치)로 교체(CON-2, 의도적 동작 변경) */
+    /** M-4: 붙여넣기 쓰기 퍼널을 writeCell(배치)로 교체(CON-2, 의도적 동작 변경)
+     * / M-4: replaces the paste write funnel with batched `writeCell` (CON-2, an
+     * intentional behavior change). */
     writeCells?: (patches: Array<{
         rowIndex: number;
         field: string;
         value: any;
     }>) => number;
+    /** 범위 선택 배선 훅 조회(범위 선택 미사용 시 `null`). / Look up the range-selection wiring hooks (or `null` when range selection is unused). */
     getRangeHooks?: () => RangeKeyboardHooks | null;
 }
+/**
+ * 키보드 내비게이션·단축키(복사/붙여넣기/행 이동/범위 선택)를 처리하는 매니저.
+ * / Handles keyboard navigation and shortcuts (copy/paste, row move, range selection).
+ *
+ * `handleKeyDown` 하나로 모든 키 입력을 받아, 클립보드·범위선택 훅·기본 셀 포커스
+ * 이동 순으로 우선순위를 매겨 위임한다.
+ * / A single `handleKeyDown` entry point receives all key input and dispatches by
+ * priority: clipboard shortcuts, range-selection hooks, then plain cell-focus movement.
+ */
 export declare class KeyboardManager<T extends Record<string, any> = any> {
     private _d;
     constructor(deps: KeyboardDeps<T>);
+    /**
+     * 그리드 컨테이너의 키다운 이벤트를 처리한다. / Handle a keydown event on the grid container.
+     *
+     * 편집 중이면 무시하고, 이후 순서대로 처리한다: 공개 `cellKeyDown` 발행 →
+     * 복사/붙여넣기(Ctrl+C/V) → 범위 채우기(Ctrl+D/R)·범위 확장(Shift+화살표) →
+     * 행 드래그(Ctrl+화살표) → 기본 셀 포커스 이동/Tab/Home/End/PageUp/PageDown →
+     * 체크·선택 토글(Space) → 편집 시작(F2/Enter) → 포커스/범위 해제(Escape).
+     * / While editing, this is a no-op. Otherwise, processing order is: emit the
+     * public `cellKeyDown` event → copy/paste (Ctrl+C/V) → range fill (Ctrl+D/R) /
+     * range extend (Shift+Arrow) → row drag (Ctrl+Arrow) → plain cell-focus movement
+     * (arrows/Tab/Home/End/PageUp/PageDown) → check/select toggle (Space) → start
+     * editing (F2/Enter) → clear focus/range (Escape).
+     *
+     * @param e - 원본 키보드 이벤트 / The originating keyboard event
+     */
     handleKeyDown(e: KeyboardEvent): void;
+    /**
+     * 현재 선택을 클립보드에 TSV 로 복사한다. / Copy the current selection to the clipboard as TSV.
+     *
+     * 우선순위: 범위 선택(있으면 그 TSV) → 단일 포커스 셀 값 → 다중 선택 행(TSV).
+     * / Priority: range selection (its TSV, if any) → single focused cell value →
+     * multi-row selection (TSV).
+     * @internal
+     */
     private _copyToClipboard;
+    /**
+     * 클립보드의 TSV 텍스트를 붙여넣는다. / Paste TSV text from the clipboard.
+     *
+     * 범위 선택이 있으면 범위 붙여넣기(타일 전개)가 우선하고, 그렇지 않으면 포커스
+     * 셀을 기준으로 배치 `writeCells` 를 호출한다.
+     * / Range paste (tiled expansion) takes priority when a range is selected;
+     * otherwise this calls batched `writeCells` anchored at the focus cell.
+     * @internal
+     */
     private _pasteFromClipboard;
 }

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

@@ -1,21 +1,22 @@
-/** 지원 마스킹 타입 */
+/** 지원 마스킹 타입. / Supported masking types. */
 export type MaskType = 'ssn' | 'phone' | 'mobile' | 'email' | 'credit' | 'account' | 'password' | 'name' | 'ip' | 'partial';
-/** 마스킹 상세 옵션 */
+/** 마스킹 상세 옵션. / Detailed masking options. */
 export interface MaskDef {
+    /** 마스킹 타입. / Masking type. */
     type: MaskType;
-    /** 마스킹 치환 문자 (기본: '*') */
+    /** 마스킹 치환 문자. 기본 '*'. / Masking replacement character. Default '*'. @defaultValue '*' */
     char?: string;
-    /** partial/account: 앞 N자리 표시 */
+    /** partial/account: 앞 N자리 표시. / partial/account: reveal the first N characters. */
     visiblePrefix?: number;
-    /** partial/account: 뒤 N자리 표시 */
+    /** partial/account: 뒤 N자리 표시. / partial/account: reveal the last N characters. */
     visibleSuffix?: number;
 }
 /**
- * 원본 값에 마스킹을 적용해 표시용 문자열을 반환.
+ * 원본 값에 마스킹을 적용해 표시용 문자열을 반환. / Apply masking to a raw value and return a display string.
  *
- * @param value   원본 값 (null/undefined → 빈 문자열 그대로 반환)
- * @param maskDef 마스킹 타입 또는 상세 옵션
- * @returns       마스킹된 문자열
+ * @param value - 원본 값 (null/undefined → 빈 문자열 그대로 반환) / Raw value (null/undefined → empty string)
+ * @param maskDef - 마스킹 타입 또는 상세 옵션 / Masking type or detailed options
+ * @returns 마스킹된 문자열 / The masked string
  *
  * @example
  * applyMask('930101-1234567', 'ssn')   // '930101-1******'