open-grid 1.2.1 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (251) hide show
  1. package/CHANGELOG.md +376 -365
  2. package/dist/{OpenGrid-0r_543Kj.cjs → OpenGrid-B7m7ei7f.cjs} +1222 -1029
  3. package/dist/{OpenGrid-HmhGVC2V.js → OpenGrid-CeUdO_fM.js} +1613 -1418
  4. package/dist/index-CeJ-0-80.cjs +260 -0
  5. package/dist/index-DnarQ4eR.js +266 -0
  6. package/dist/index-DrCPRuYi.js +548 -0
  7. package/dist/index-JjfWY3Bt.cjs +520 -0
  8. package/dist/open-grid-base.css +12 -1
  9. package/dist/open-grid-react.cjs +1 -1
  10. package/dist/open-grid-react.js +1 -1
  11. package/dist/open-grid-vue.cjs +7 -7
  12. package/dist/open-grid-vue.js +2 -2
  13. package/dist/open-grid.cjs +1 -1
  14. package/dist/open-grid.js +2 -2
  15. package/dist/types/bench/perf.d.ts +14 -8
  16. package/dist/types/core/AppearanceResolver.d.ts +98 -11
  17. package/dist/types/core/CFRenderBridge.d.ts +13 -0
  18. package/dist/types/core/CellTypeRegistry.d.ts +24 -0
  19. package/dist/types/core/ColumnLayout.d.ts +100 -2
  20. package/dist/types/core/CrossGridMapper.d.ts +43 -5
  21. package/dist/types/core/DataLayer.d.ts +210 -15
  22. package/dist/types/core/DragVisuals.d.ts +33 -4
  23. package/dist/types/core/EventEmitter.d.ts +54 -0
  24. package/dist/types/core/FormulaEngine.d.ts +15 -4
  25. package/dist/types/core/GridRenderer.d.ts +143 -10
  26. package/dist/types/core/GroupEngine.d.ts +68 -10
  27. package/dist/types/core/MathUtils.d.ts +58 -5
  28. package/dist/types/core/MergeEngine.d.ts +45 -10
  29. package/dist/types/core/OGDecimal.d.ts +144 -13
  30. package/dist/types/core/OpenGrid.d.ts +99 -0
  31. package/dist/types/core/PivotEngine.d.ts +37 -0
  32. package/dist/types/core/RowDragDrop.d.ts +52 -6
  33. package/dist/types/core/SkinRegistry.d.ts +4 -0
  34. package/dist/types/core/TreeEngine.d.ts +60 -6
  35. package/dist/types/core/VirtualScroll.d.ts +64 -0
  36. package/dist/types/core/a11y/AccessibilityAdapter.d.ts +103 -0
  37. package/dist/types/core/a11y/AriaIntent.d.ts +34 -0
  38. package/dist/types/core/a11y/KeyboardInteractionModel.d.ts +64 -0
  39. package/dist/types/core/a11y/LiveRegionController.d.ts +89 -0
  40. package/dist/types/core/a11y/OverlayStack.d.ts +36 -0
  41. package/dist/types/core/a11y/VisualEquivRegistry.d.ts +37 -0
  42. package/dist/types/core/a11y/index.d.ts +13 -0
  43. package/dist/types/core/a11y/ports.d.ts +24 -0
  44. package/dist/types/core/appearance/Appearance.d.ts +68 -0
  45. package/dist/types/core/appearance/AppearanceAxis.d.ts +94 -0
  46. package/dist/types/core/appearance/AppearanceComposer.d.ts +45 -0
  47. package/dist/types/core/appearance/AppearanceProvider.d.ts +50 -0
  48. package/dist/types/core/appearance/AppearanceView.d.ts +51 -0
  49. package/dist/types/core/appearance/DensityRegistry.d.ts +36 -0
  50. package/dist/types/core/appearance/ResolvedAppearanceSnapshot.d.ts +84 -0
  51. package/dist/types/core/appearance/TextureRegistry.d.ts +32 -0
  52. package/dist/types/core/appearance/ThemeMetaRegistry.d.ts +67 -0
  53. package/dist/types/core/appearance/axisAdapters.d.ts +37 -0
  54. package/dist/types/core/appearance/defaults.d.ts +10 -0
  55. package/dist/types/core/appearance/index.d.ts +20 -0
  56. package/dist/types/core/appearance/tokenCatalog.d.ts +30 -0
  57. package/dist/types/core/cf/CFEngine.d.ts +56 -0
  58. package/dist/types/core/cf/CFEvaluator.d.ts +24 -0
  59. package/dist/types/core/cf/CFRule.d.ts +127 -0
  60. package/dist/types/core/cf/ColorScale.d.ts +49 -0
  61. package/dist/types/core/cf/InkResolver.d.ts +33 -0
  62. package/dist/types/core/cf/appearance.d.ts +20 -0
  63. package/dist/types/core/cf/encoders.d.ts +61 -0
  64. package/dist/types/core/cf/eval-types.d.ts +93 -0
  65. package/dist/types/core/cf/index.d.ts +21 -0
  66. package/dist/types/core/cf/lineage.d.ts +32 -0
  67. package/dist/types/core/cf/predicates.d.ts +27 -0
  68. package/dist/types/core/cf/serialize.d.ts +46 -0
  69. package/dist/types/core/chart/CanvasAdapter.d.ts +50 -1
  70. package/dist/types/core/chart/DataExtractor.d.ts +53 -12
  71. package/dist/types/core/chart/a11y.d.ts +22 -0
  72. package/dist/types/core/chart/chart-type-registry.d.ts +53 -0
  73. package/dist/types/core/chart/downsample-report.d.ts +36 -0
  74. package/dist/types/core/chart/downsample.d.ts +26 -1
  75. package/dist/types/core/chart/engine/ChartEngineRegistry.d.ts +52 -0
  76. package/dist/types/core/chart/geometry.d.ts +96 -0
  77. package/dist/types/core/chart/hittest.d.ts +21 -3
  78. package/dist/types/core/chart/palette.d.ts +96 -12
  79. package/dist/types/core/chart/parity.d.ts +12 -0
  80. package/dist/types/core/chart/provenance.d.ts +47 -0
  81. package/dist/types/core/chart/scales.d.ts +28 -1
  82. package/dist/types/core/chart/scene.d.ts +102 -0
  83. package/dist/types/core/chart/server.d.ts +36 -0
  84. package/dist/types/core/chart/surfaces/CanvasSurface.d.ts +48 -0
  85. package/dist/types/core/chart/surfaces/ServerRasterSurface.d.ts +26 -0
  86. package/dist/types/core/chart/surfaces/SvgSurface.d.ts +24 -0
  87. package/dist/types/core/chart/surfaces/pattern-overlay.d.ts +24 -0
  88. package/dist/types/core/command/CommandBus.d.ts +51 -0
  89. package/dist/types/core/command/CommandRegistry.d.ts +43 -0
  90. package/dist/types/core/command/CommandStack.d.ts +38 -0
  91. package/dist/types/core/command/ICommand.d.ts +110 -0
  92. package/dist/types/core/command/commands/CellWriteCommand.d.ts +32 -0
  93. package/dist/types/core/command/commands/CompositeCommand.d.ts +17 -0
  94. package/dist/types/core/command/commands/RowCommands.d.ts +39 -0
  95. package/dist/types/core/command/index.d.ts +9 -0
  96. package/dist/types/core/command/support.d.ts +51 -0
  97. package/dist/types/core/coordinate/ColumnMetrics.d.ts +30 -0
  98. package/dist/types/core/coordinate/CoordinateKernel.d.ts +88 -0
  99. package/dist/types/core/coordinate/FrozenPanes.d.ts +29 -0
  100. package/dist/types/core/coordinate/MergeSourceAdapter.d.ts +18 -0
  101. package/dist/types/core/coordinate/NodeBudget.d.ts +33 -0
  102. package/dist/types/core/coordinate/ResizeGovernor.d.ts +50 -0
  103. package/dist/types/core/coordinate/RowMetrics.d.ts +37 -0
  104. package/dist/types/core/coordinate/ViewPermutation.d.ts +23 -0
  105. package/dist/types/core/coordinate/index.d.ts +10 -0
  106. package/dist/types/core/coordinate/ports.d.ts +45 -0
  107. package/dist/types/core/coordinate/types.d.ts +76 -0
  108. package/dist/types/core/detail/DetailGlyph.d.ts +42 -7
  109. package/dist/types/core/detail/DetailSplice.d.ts +42 -11
  110. package/dist/types/core/detail/DetailState.d.ts +80 -11
  111. package/dist/types/core/detail/SubgridCache.d.ts +72 -10
  112. package/dist/types/core/detail/index.d.ts +8 -0
  113. package/dist/types/core/domain/AggregateResult.d.ts +54 -0
  114. package/dist/types/core/domain/CellAddress.d.ts +61 -0
  115. package/dist/types/core/domain/CellValueAccess.d.ts +29 -0
  116. package/dist/types/core/domain/Delta.d.ts +37 -0
  117. package/dist/types/core/domain/DomainValue.d.ts +80 -0
  118. package/dist/types/core/domain/Missing.d.ts +65 -0
  119. package/dist/types/core/domain/Money.d.ts +42 -0
  120. package/dist/types/core/domain/NormalizationBasis.d.ts +47 -0
  121. package/dist/types/core/domain/Plain.d.ts +45 -0
  122. package/dist/types/core/domain/Quantity.d.ts +32 -0
  123. package/dist/types/core/domain/Ratios.d.ts +100 -0
  124. package/dist/types/core/domain/ThresholdSet.d.ts +46 -0
  125. package/dist/types/core/domain/ValueType.d.ts +71 -0
  126. package/dist/types/core/domain/rounding.d.ts +25 -0
  127. package/dist/types/core/domain/strategies.d.ts +38 -0
  128. package/dist/types/core/editors/DateEditor.d.ts +18 -0
  129. package/dist/types/core/editors/SelectEditor.d.ts +29 -0
  130. package/dist/types/core/export/ChannelRegistry.d.ts +18 -0
  131. package/dist/types/core/export/ExportManifest.d.ts +13 -0
  132. package/dist/types/core/export/GridArtifactSource.d.ts +62 -0
  133. package/dist/types/core/export/Provenance.d.ts +34 -0
  134. package/dist/types/core/export/StreamPump.d.ts +28 -0
  135. package/dist/types/core/export/channels/CsvChannel.d.ts +20 -0
  136. package/dist/types/core/export/channels/JsonChannel.d.ts +18 -0
  137. package/dist/types/core/export/channels/XlsxChannel.d.ts +53 -0
  138. package/dist/types/core/export/channels/XmlChannel.d.ts +21 -0
  139. package/dist/types/core/export/channels/capabilities.d.ts +13 -0
  140. package/dist/types/core/export/index.d.ts +24 -0
  141. package/dist/types/core/export/print/OutputChannelAdapter.d.ts +61 -0
  142. package/dist/types/core/export/print/Paginator.d.ts +48 -0
  143. package/dist/types/core/export/print/PrintRenderTarget.d.ts +36 -0
  144. package/dist/types/core/export/sinks.d.ts +40 -0
  145. package/dist/types/core/export/types.d.ts +211 -0
  146. package/dist/types/core/extension/DeprecationManager.d.ts +42 -0
  147. package/dist/types/core/extension/IExtension.d.ts +90 -0
  148. package/dist/types/core/extension/Registry.d.ts +142 -0
  149. package/dist/types/core/extension/SlotRegistry.d.ts +46 -0
  150. package/dist/types/core/extension/adapters.d.ts +44 -0
  151. package/dist/types/core/extension/conformance.d.ts +47 -0
  152. package/dist/types/core/extension/index.d.ts +16 -0
  153. package/dist/types/core/extension/registries.d.ts +31 -0
  154. package/dist/types/core/extension/reserved.d.ts +10 -0
  155. package/dist/types/core/format/DisplayFormatter.d.ts +47 -0
  156. package/dist/types/core/format/FormatCache.d.ts +20 -0
  157. package/dist/types/core/format/FormatterRegistry.d.ts +22 -0
  158. package/dist/types/core/format/grammar/AstRenderer.d.ts +10 -0
  159. package/dist/types/core/format/grammar/FormatCompiler.d.ts +16 -0
  160. package/dist/types/core/format/index.d.ts +55 -0
  161. package/dist/types/core/format/pipeline/DomainTypeResolver.d.ts +8 -0
  162. package/dist/types/core/format/pipeline/LocaleFormat.d.ts +11 -0
  163. package/dist/types/core/format/pipeline/ValueInterpreter.d.ts +8 -0
  164. package/dist/types/core/format/policy/MaskPolicy.d.ts +8 -0
  165. package/dist/types/core/format/policy/NegativePolicy.d.ts +12 -0
  166. package/dist/types/core/format/policy/NullPolicy.d.ts +10 -0
  167. package/dist/types/core/format/policy/TruncatePolicy.d.ts +11 -0
  168. package/dist/types/core/format/types.d.ts +292 -0
  169. package/dist/types/core/formula/CalcCacheStore.d.ts +89 -0
  170. package/dist/types/core/formula/CalcProvenance.d.ts +44 -0
  171. package/dist/types/core/formula/CalcService.d.ts +137 -0
  172. package/dist/types/core/formula/CyclePathReporter.d.ts +28 -0
  173. package/dist/types/core/formula/FormulaEvaluator.d.ts +35 -1
  174. package/dist/types/core/formula/FormulaGraph.d.ts +84 -7
  175. package/dist/types/core/formula/FormulaParser.d.ts +9 -0
  176. package/dist/types/core/formula/FormulaStore.d.ts +63 -1
  177. package/dist/types/core/formula/FunctionRegistry.d.ts +138 -0
  178. package/dist/types/core/formula/Generation.d.ts +86 -0
  179. package/dist/types/core/formula/RecalcCoordinator.d.ts +151 -9
  180. package/dist/types/core/formula/ReferenceRewriter.d.ts +81 -0
  181. package/dist/types/core/formula/functions/essential.d.ts +3 -0
  182. package/dist/types/core/formula/functions/extended/index.d.ts +10 -0
  183. package/dist/types/core/formula/normalizeRefs.d.ts +34 -3
  184. package/dist/types/core/formula/numericLiteral.d.ts +11 -1
  185. package/dist/types/core/formula/serializeFormula.d.ts +10 -1
  186. package/dist/types/core/host/CapabilityRegistry.d.ts +61 -0
  187. package/dist/types/core/host/GridHostDriver.d.ts +27 -0
  188. package/dist/types/core/host/GridHostPort.d.ts +37 -0
  189. package/dist/types/core/host/SliceOwnershipGuard.d.ts +27 -0
  190. package/dist/types/core/host/archCheck.d.ts +26 -0
  191. package/dist/types/core/host/index.d.ts +6 -0
  192. package/dist/types/core/host/reconcile.d.ts +22 -0
  193. package/dist/types/core/i18n/LocaleContext.d.ts +40 -0
  194. package/dist/types/core/i18n/types.d.ts +26 -1
  195. package/dist/types/core/icons/bootstrap-icons.d.ts +4 -2
  196. package/dist/types/core/quality/ContrastAuditor.d.ts +64 -0
  197. package/dist/types/core/quality/DeterminismKernel.d.ts +68 -0
  198. package/dist/types/core/quality/PerfBaseline.d.ts +23 -0
  199. package/dist/types/core/quality/PerfSpec.d.ts +95 -0
  200. package/dist/types/core/quality/RealBrowserGate.d.ts +69 -0
  201. package/dist/types/core/quality/RegressionJudge.d.ts +35 -0
  202. package/dist/types/core/quality/ReleaseGate.d.ts +94 -0
  203. package/dist/types/core/quality/VisualRegression.d.ts +74 -0
  204. package/dist/types/core/quality/hooks.d.ts +53 -0
  205. package/dist/types/core/quality/index.d.ts +20 -0
  206. package/dist/types/core/quality/pixelMetrics.d.ts +24 -0
  207. package/dist/types/core/range/ClipboardCodec.d.ts +46 -4
  208. package/dist/types/core/range/FillEngine.d.ts +69 -9
  209. package/dist/types/core/range/RangeModel.d.ts +100 -13
  210. package/dist/types/core/range/types.d.ts +27 -11
  211. package/dist/types/core/realtime/BackpressureScheduler.d.ts +0 -0
  212. package/dist/types/core/realtime/FreshnessClock.d.ts +34 -0
  213. package/dist/types/core/realtime/IRealtimeSource.d.ts +82 -0
  214. package/dist/types/core/realtime/LiveStateGuard.d.ts +23 -0
  215. package/dist/types/core/realtime/PollingSource.d.ts +42 -0
  216. package/dist/types/core/realtime/RealtimeController.d.ts +54 -0
  217. package/dist/types/core/realtime/RtAnnouncePolicy.d.ts +53 -0
  218. package/dist/types/core/realtime/RtApplyCommand.d.ts +29 -0
  219. package/dist/types/core/realtime/RtChartTargetTrigger.d.ts +26 -0
  220. package/dist/types/core/realtime/StreamingSource.d.ts +47 -0
  221. package/dist/types/core/realtime/backoff.d.ts +12 -0
  222. package/dist/types/core/realtime/index.d.ts +13 -0
  223. package/dist/types/core/realtime/ports.d.ts +80 -0
  224. package/dist/types/core/render/CellApplier.d.ts +18 -0
  225. package/dist/types/core/render/CellErrorBoundary.d.ts +65 -0
  226. package/dist/types/core/render/CellPipeline.d.ts +39 -0
  227. package/dist/types/core/render/CellRenderRequest.d.ts +209 -0
  228. package/dist/types/core/render/CellStageRegistry.d.ts +53 -0
  229. package/dist/types/core/render/OverlayCompositor.d.ts +38 -0
  230. package/dist/types/core/render/RenderBudget.d.ts +67 -0
  231. package/dist/types/core/render/contrast.d.ts +33 -0
  232. package/dist/types/core/render/index.d.ts +35 -0
  233. package/dist/types/core/render/stages/BackgroundStage.d.ts +14 -0
  234. package/dist/types/core/render/stages/DecoratorStage.d.ts +12 -0
  235. package/dist/types/core/render/stages/OverlayStage.d.ts +12 -0
  236. package/dist/types/core/render/stages/ValueRendererStage.d.ts +15 -0
  237. package/dist/types/core/render/stages/index.d.ts +14 -0
  238. package/dist/types/core/state/AutosaveController.d.ts +63 -0
  239. package/dist/types/core/state/IStatePersistence.d.ts +59 -0
  240. package/dist/types/core/state/MultiTabGuard.d.ts +33 -0
  241. package/dist/types/core/state/SchemaMigrator.d.ts +33 -0
  242. package/dist/types/core/state/SemVerPolicy.d.ts +39 -0
  243. package/dist/types/core/state/StateCodec.d.ts +75 -0
  244. package/dist/types/core/state/index.d.ts +6 -0
  245. package/dist/types/core/types.d.ts +17 -0
  246. package/dist/types/react/OpenGrid.d.ts +54 -0
  247. package/dist/types/react/index.d.ts +5 -0
  248. package/dist/types/realtime/index.d.ts +1 -0
  249. package/dist/types/vue/index.d.ts +5 -0
  250. package/dist/types/vue/types.d.ts +35 -0
  251. package/package.json +112 -111
@@ -1,5 +1,6 @@
1
1
  /**
2
2
  * DetailGlyph — F2 디테일 expander 글리프/aria 정책 (C10 R-DETAIL-GLYPH, HANMS-06 해소).
3
+ * / DetailGlyph — F2 detail-expander glyph / aria policy (C10 R-DETAIL-GLYPH, resolves review item HANMS-06).
3
4
  *
4
5
  * 계약 근거:
5
6
  * - docs/design/grid-features-2026-07/15_cross_contracts.md C10 "R-DETAIL-GLYPH": detail expander는
@@ -8,43 +9,77 @@
8
9
  * - docs/design/grid-features-2026-07/11_design_F2_v2.md §4.5(글리프/aria 상세), §1.2 NFR-5(접근성
9
10
  * 측정가능 AC: aria-expanded 토글, aria-controls 연결), §4.3(panel.id 규칙 = aria-controls 타겟),
10
11
  * C8.4(터치 히트 타겟 ≥44×44 CSS px).
12
+ * / Contract basis:
13
+ * - 15_cross_contracts.md C10 "R-DETAIL-GLYPH": the detail expander **must not use a chevron (▸/▾)**.
14
+ * It is distinguished from the tree chevron by a separate glyph (`⊕/⊖` or `▤ detail`) + tooltip ("View detail")
15
+ * + aria-label. A chevron is allowed only when the tree is **inactive**.
16
+ * - 11_design_F2_v2.md §4.5 (glyph/aria detail), §1.2 NFR-5 (measurable accessibility AC: aria-expanded toggle,
17
+ * aria-controls linkage), §4.3 (panel.id rule = aria-controls target), C8.4 (touch hit target ≥44×44 CSS px).
11
18
  *
12
19
  * 렌더 배선(GridRenderer expander 셀)이 이 모듈의 순수 함수/상수를 소비해 실제 DOM 속성을 채운다.
13
20
  * 이 파일은 DOM 을 만들지 않는다 — 문자열/속성 값만 생성.
21
+ * / Render wiring (GridRenderer expander cell) consumes this module's pure functions/constants to populate the
22
+ * actual DOM attributes. This file creates no DOM — only string/attribute values.
14
23
  */
15
24
  /** i18n: 글리프 aria/툴팁 로케일 해석기(주입 없으면 전역 t). / i18n: glyph aria/tooltip resolver (global t when not injected). */
16
25
  export type DetailGlyphT = (key: string, params?: Record<string, string | number>) => string;
17
- /** 트리 셰브론(▸/▾)과 충돌하지 않는 전용 글리프(C10 기본값). */
26
+ /** 접힘 상태 전용 글리프(트리 셰브론 ▸/▾과 충돌하지 않는 C10 기본값). / Collapsed-state glyph (C10 default that does not collide with the tree chevron ▸/▾). */
18
27
  export declare const DETAIL_GLYPH_COLLAPSED = "\u2295";
28
+ /** 펼침 상태 전용 글리프(트리 셰브론과 충돌하지 않는 C10 기본값). / Expanded-state glyph (C10 default that does not collide with the tree chevron). */
19
29
  export declare const DETAIL_GLYPH_EXPANDED = "\u2296";
20
- /** 라벨형 대안(옵션) — 기본은 원형 글리프, toggle:'first-cell' 등 배치에서 선택적으로 사용. */
30
+ /** 라벨형 대안(옵션) — 기본은 원형 글리프, toggle:'first-cell' 등 배치에서 선택적으로 사용. / Label-style alternative (optional) — the circular glyph is default; used selectively in layouts like toggle:'first-cell'. */
21
31
  export declare const DETAIL_GLYPH_LABEL_COLLAPSED = "\u25A4 \uC0C1\uC138";
32
+ /** 툴팁 고정 문구(C10 "상세 보기"). / Fixed tooltip text (C10 "View detail"). */
22
33
  export declare const DETAIL_GLYPH_TOOLTIP = "\uC0C1\uC138 \uBCF4\uAE30";
23
- /** C8.4: expander 히트 타겟 최소 CSS px(가로/세로). */
34
+ /** C8.4: expander 히트 타겟 최소 CSS px(가로/세로). / C8.4: minimum expander hit-target size in CSS px (width/height). */
24
35
  export declare const DETAIL_EXPANDER_MIN_HIT_TARGET_PX = 44;
36
+ /** getDetailGlyph 반환 구조 — 렌더 배선이 소비할 글리프/aria/title 묶음. / Return shape of getDetailGlyph — glyph/aria/title bundle for render wiring to consume. */
25
37
  export interface DetailGlyphInfo {
26
- /** 화면에 그릴 문자(셰브론 아님, C10). */
38
+ /** 화면에 그릴 문자(셰브론 아님, C10). / Character to render (not a chevron, C10). */
27
39
  glyph: string;
28
- /** expander 자체 aria-label(NFR-5, HANMS-06 — SR 에서 트리 토글과 구분). */
40
+ /** expander 자체 aria-label(NFR-5, HANMS-06 — SR 에서 트리 토글과 구분). / The expander's own aria-label (NFR-5, HANMS-06 — distinguished from the tree toggle for screen readers). */
29
41
  ariaLabel: string;
30
- /** 툴팁 title 속성(C10 "상세 보기" 고정 문구). */
42
+ /** 툴팁 title 속성(C10 "상세 보기" 고정 문구). / Tooltip title attribute (C10 fixed text "View detail"). */
31
43
  title: string;
32
44
  }
33
45
  /**
34
46
  * 펼침 여부에 따른 글리프/aria-label/title 조합을 반환한다. 트리 셰브론과 절대 겹치지 않는
35
47
  * 문자셋만 사용(C10 R-DETAIL-GLYPH 하드 룰).
48
+ * / Return the glyph/aria-label/title combination for the given expanded state. Uses only a character set that
49
+ * never overlaps the tree chevron (C10 R-DETAIL-GLYPH hard rule).
50
+ *
51
+ * @param expanded - 현재 펼침 여부 / Whether currently expanded
52
+ * @param t - i18n 로케일 해석기(미주입 시 전역 t) / i18n locale resolver (global t when not injected)
53
+ * @returns 글리프/aria-label/title 묶음 / glyph/aria-label/title bundle
36
54
  */
37
55
  export declare function getDetailGlyph(expanded: boolean, t?: DetailGlyphT): DetailGlyphInfo;
38
- /** NFR-5(1): 마스터 행 `aria-expanded` 값(문자열 — DOM setAttribute 그대로 사용). */
56
+ /**
57
+ * NFR-5(1): 마스터 행 `aria-expanded` 값(문자열 — DOM setAttribute 그대로 사용).
58
+ * / NFR-5(1): master-row `aria-expanded` value (string — used directly in DOM setAttribute).
59
+ *
60
+ * @param expanded - 현재 펼침 여부 / Whether currently expanded
61
+ * @returns 'true' 또는 'false' 문자열 / 'true' or 'false' string
62
+ */
39
63
  export declare function getMasterRowAriaExpanded(expanded: boolean): 'true' | 'false';
40
64
  /**
41
65
  * NFR-5(2)/§4.3: 패널 DOM id 규칙. expander 의 `aria-controls` 와 패널의 `id` 는 반드시 이
42
66
  * 한 함수로만 생성해 두 값의 불일치를 구조적으로 차단한다.
67
+ * / NFR-5(2)/§4.3: panel DOM id rule. The expander's `aria-controls` and the panel's `id` must be generated only
68
+ * by this single function, structurally preventing any mismatch between the two.
69
+ *
70
+ * @param rowId - stable rowId / stable rowId
71
+ * @returns 패널 DOM id(`og-detail-<rowId>`) / Panel DOM id (`og-detail-<rowId>`)
43
72
  */
44
73
  export declare function getDetailPanelId(rowId: string): string;
45
74
  /**
46
75
  * §4.5 "트리 동시 활성 시 충돌 해소" 규칙의 판별 헬퍼: 트리가 활성화된 그리드에서는 셰브론을
47
76
  * 쓸 수 없다(트리 셰브론과 자리를 공유하지 않도록 렌더 배선이 별도 컬럼/색을 쓰게 강제하는 신호).
48
77
  * 트리 비활성일 때만 셰브론 허용 여부를 true 로 반환한다.
78
+ * / Decision helper for the §4.5 "resolve conflict when tree is simultaneously active" rule: a chevron cannot be
79
+ * used in a tree-active grid (a signal that forces render wiring to use a separate column/color so it does not
80
+ * share space with the tree chevron). Returns true only when the tree is inactive.
81
+ *
82
+ * @param treeActive - 트리 활성 여부 / Whether the tree is active
83
+ * @returns 셰브론 허용 여부 / Whether a chevron is allowed
49
84
  */
50
85
  export declare function isChevronAllowedForDetail(treeActive: boolean): boolean;
@@ -1,5 +1,6 @@
1
1
  /**
2
2
  * DetailSplice — 상류 flat 배열에 F2 디테일 head/filler 의사행을 끼워 넣는 순수 함수.
3
+ * / DetailSplice — pure function that splices F2 detail head/filler pseudo-rows into the upstream flat array.
3
4
  *
4
5
  * 계약 근거:
5
6
  * - docs/design/grid-features-2026-07/11_design_F2_v2.md §2.2/§3.2(단방향 합성 체인의 마지막 단계:
@@ -7,61 +8,91 @@
7
8
  * §4.1(DetailHeadRow/DetailFillerRow 형태), §7(그룹 헤더엔 미부착·트리 데이터 행엔 허용)
8
9
  * - docs/design/grid-features-2026-07/15_cross_contracts.md C0.3(FlatRowRef.kind
9
10
  * 'detailHead'/'detailFiller' — filler 에 writeCell 절대 금지의 판별 재료)
11
+ * / Contract basis:
12
+ * - 11_design_F2_v2.md §2.2/§3.2 (last stage of the one-way composition chain:
13
+ * plain → group/tree (owned by GroupTreeManager) → **detail splice (this file)** → FlatRowModel.updateFlatModel),
14
+ * §4.1 (DetailHeadRow/DetailFillerRow shape), §7 (not attached to group headers; allowed on tree data rows)
15
+ * - 15_cross_contracts.md C0.3 (FlatRowRef.kind 'detailHead'/'detailFiller' — basis for absolutely forbidding
16
+ * writeCell on fillers)
10
17
  *
11
18
  * MVP는 (b) 정수-슬롯: 디테일 높이 = span(=ceil(height/rowHeight)) × rowHeight 개의 **정수 rowHeight
12
19
  * 슬롯**으로 표현한다. 1개 head(span 보유) + (span-1)개 filler. VirtualScroll 은 이 슬롯들도 여느
13
20
  * 인덱스와 동일한 rowHeight 로 보고 무변경(CON-1)으로 남는다.
21
+ * / MVP uses (b) integer slots: the detail height is represented as span (=ceil(height/rowHeight)) **integer
22
+ * rowHeight slots**. One head (holding span) + (span-1) fillers. VirtualScroll treats these slots at the same
23
+ * rowHeight as any other index and stays unchanged (CON-1).
14
24
  *
15
25
  * ⚠️ 이 함수는 실제 GroupTreeManager/FlatRowModel(둘 다 이 작업과 동시에 변경 중)을 import 하지
16
26
  * 않는다. 대신 GridRenderer.ts 가 이미 소비하는 런타임 관례(`_isGroup`/`_isTree` 플래그, 트리 노드의
17
27
  * `.data`)를 로컬 타입 가드로만 재선언해 상류 flat 항목을 분류한다 — 배선 단계에서 실제 등록
18
28
  * 어댑터가 이 함수를 호출한다.
29
+ * / This function does not import the real GroupTreeManager/FlatRowModel (both changing concurrently with this
30
+ * work). Instead it reclassifies upstream flat items using only local type guards for the runtime conventions
31
+ * GridRenderer.ts already consumes (`_isGroup`/`_isTree` flags, a tree node's `.data`) — a real registration
32
+ * adapter calls this function at the wiring stage.
19
33
  */
20
- /** GroupTreeManager 산출물(GroupRow)과 동형의 최소 구조 — 로컬 판별용(실제 타입 import 안 함). */
34
+ /** GroupTreeManager 산출물(GroupRow)과 동형의 최소 구조 — 로컬 판별용(실제 타입 import 안 함). / Minimal shape isomorphic to the GroupTreeManager output (GroupRow) — for local discrimination only (real type not imported). */
21
35
  interface GroupLikeItem {
22
36
  _isGroup: true;
23
37
  }
24
- /** TreeEngine TreeNode 와 동형의 최소 구조 — 로컬 판별용(실제 타입 import 안 함). */
38
+ /** TreeEngine TreeNode 와 동형의 최소 구조 — 로컬 판별용(실제 타입 import 안 함). / Minimal shape isomorphic to a TreeEngine TreeNode — for local discrimination only (real type not imported). */
25
39
  interface TreeLikeItem<T = any> {
26
40
  _isTree: true;
27
41
  data: T;
28
42
  }
29
- /** F2 디테일 head 의사행(§4.1). span 개의 rowHeight 슬롯 중 첫 슬롯 — 실제 패널이 여기 그려진다. */
43
+ /** F2 디테일 head 의사행(§4.1). span 개의 rowHeight 슬롯 중 첫 슬롯 — 실제 패널이 여기 그려진다. / F2 detail head pseudo-row (§4.1). The first of span rowHeight slots — the actual panel is drawn here. */
30
44
  export interface DetailHeadItem<T = any> {
45
+ /** head 의사행 판별 플래그. / Discriminator flag for a head pseudo-row. */
31
46
  _isDetailHead: true;
47
+ /** 마스터의 stable rowId. / Master's stable rowId. */
32
48
  _rowId: string;
33
- /** 마스터 원본 flat 항목(트리/그룹 컨텍스트 유지용, optional — §4.1). */
49
+ /** 마스터 원본 flat 항목(트리/그룹 컨텍스트 유지용, optional — §4.1). / Original master flat item (retains tree/group context, optional — §4.1). */
34
50
  _masterFlatBase?: T | GroupLikeItem | TreeLikeItem<T>;
35
- /** k = ceil(height/rowHeight). 슬롯 총 개수(head 포함). */
51
+ /** k = ceil(height/rowHeight). 슬롯 총 개수(head 포함). / k = ceil(height/rowHeight). Total slot count (including head). */
36
52
  _span: number;
37
53
  }
38
- /** F2 디테일 filler 의사행(§4.1). span-1 개. renderBody 는 이 인덱스를 만나면 continue(패널이 덮음). */
54
+ /** F2 디테일 filler 의사행(§4.1). span-1 개. renderBody 는 이 인덱스를 만나면 continue(패널이 덮음). / F2 detail filler pseudo-row (§4.1). span-1 of them. renderBody continues past this index (the panel covers it). */
39
55
  export interface DetailFillerItem {
56
+ /** filler 의사행 판별 플래그. / Discriminator flag for a filler pseudo-row. */
40
57
  _isDetailFiller: true;
58
+ /** 마스터의 stable rowId. / Master's stable rowId. */
41
59
  _rowId: string;
42
60
  }
61
+ /** splice 후 flat 배열의 항목 합집합(원본 행/그룹/트리/디테일 의사행). / Union of items in the spliced flat array (source row / group / tree / detail pseudo-rows). */
43
62
  export type DetailSplicedItem<T = any> = T | GroupLikeItem | TreeLikeItem<T> | DetailHeadItem<T> | DetailFillerItem;
44
- /** 행별 슬롯수 콜백(옵션) — 지정 시 고정 height 대신 이 값을 사용(반올림 후 ceil 없이 그대로 슬롯수로 채택). */
63
+ /** 행별 슬롯수 콜백(옵션) — 지정 시 고정 height 대신 이 값을 사용(반올림 후 ceil 없이 그대로 슬롯수로 채택). / Per-row slot-count callback (optional) — when set, used instead of a fixed height (floored, then taken directly as the slot count without ceil). */
45
64
  export type SlotCountFn<T = any> = (row: T, rowId: string) => number;
65
+ /** spliceDetails 옵션. / Options for spliceDetails. */
46
66
  export interface DetailSpliceOptions<T = any> {
47
- /** DetailState.expandedRowIds — stable rowId 앵커(정렬/필터 넘어 보존, FR-4/C0.5). */
67
+ /** DetailState.expandedRowIds — stable rowId 앵커(정렬/필터 넘어 보존, FR-4/C0.5). / DetailState.expandedRowIds — stable rowId anchors (preserved across sort/filter, FR-4/C0.5). */
48
68
  expandedRowIds: ReadonlySet<string>;
49
- /** 마스터 후보 row(T)에서 stable rowId 를 뽑는다. undefined/null 이면 해당 항목은 detail 부착 대상에서 제외. */
69
+ /** 마스터 후보 row(T)에서 stable rowId 를 뽑는다. undefined/null 이면 해당 항목은 detail 부착 대상에서 제외. / Extract a stable rowId from a candidate master row (T). undefined/null excludes that item from detail attachment. */
50
70
  getRowId: (row: T) => string | undefined | null;
71
+ /** 그리드 행 높이(px). / Grid row height (px). */
51
72
  rowHeight: number;
52
- /** masterDetail.height(px). 기본 200. getSlotCount 미지정 시 이 값으로 ceil(height/rowHeight) 계산(EC-10 양자화). */
73
+ /** masterDetail.height(px). 기본 200. getSlotCount 미지정 시 이 값으로 ceil(height/rowHeight) 계산(EC-10 양자화). / masterDetail.height (px). Default 200. When getSlotCount is unset, computes ceil(height/rowHeight) from this (EC-10 quantization). */
53
74
  height?: number;
54
- /** 지정 시 height 대신 이 콜백으로 슬롯수(정수, 최소 1) 결정 — masterDetail.detailRowCount 류 확장 지점. */
75
+ /** 지정 시 height 대신 이 콜백으로 슬롯수(정수, 최소 1) 결정 — masterDetail.detailRowCount 류 확장 지점. / When set, determines slot count (integer, min 1) via this callback instead of height — an extension point akin to masterDetail.detailRowCount. */
55
76
  getSlotCount?: SlotCountFn<T>;
56
77
  }
57
78
  /**
58
79
  * baseFlat(plain rows 또는 GroupTreeManager 산출물)을 순회하며, 펼쳐진 stable rowId 를 만난
59
80
  * 마스터 행 **직후**에 `[head, ...filler×(span-1)]` 를 삽입한다(§4.1). 순수 함수 — baseFlat 은
60
81
  * 변경하지 않고 새 배열을 반환한다.
82
+ * / Iterate baseFlat (plain rows or GroupTreeManager output) and, **immediately after** a master row whose
83
+ * stable rowId is expanded, insert `[head, ...filler×(span-1)]` (§4.1). Pure function — returns a new array
84
+ * without mutating baseFlat.
61
85
  *
62
86
  * expandedRowIds 가 비어 있으면(펼침 0/F2 비활성) 항등에 가깝게 동작하되, §3.2 v2 규범대로
63
87
  * "DetailManager는 항상 최종 flat 소유자"이므로 얕은 복사본을 반환한다(호출자가 항상 새 배열을
64
88
  * updateFlatModel 에 넘기는 계약을 일관되게 유지하기 위함 — 참조 동일성에 의존한 버그 예방).
89
+ * / When expandedRowIds is empty (0 expansions / F2 inactive) it behaves near-identity but, per §3.2 v2 norm
90
+ * "DetailManager is always the final flat owner", still returns a shallow copy (so the caller consistently keeps
91
+ * the contract of always passing a new array to updateFlatModel — preventing bugs that rely on reference identity).
92
+ *
93
+ * @param baseFlat - 상류 flat 배열(불변 취급) / Upstream flat array (treated as immutable)
94
+ * @param opts - splice 옵션(펼침 집합/rowId 추출/높이 등) / Splice options (expanded set / rowId extractor / height, etc.)
95
+ * @returns 디테일 의사행이 삽입된 새 flat 배열 / New flat array with detail pseudo-rows inserted
65
96
  */
66
97
  export declare function spliceDetails<T = any>(baseFlat: ReadonlyArray<DetailSplicedItem<T>>, opts: DetailSpliceOptions<T>): DetailSplicedItem<T>[];
67
98
  export {};
@@ -1,67 +1,136 @@
1
1
  /**
2
2
  * DetailState — F2 마스터/디테일 펼침 상태 (헤드리스).
3
+ * / DetailState — F2 master/detail expansion state (headless).
3
4
  *
4
5
  * 계약 근거:
5
6
  * - docs/design/grid-features-2026-07/11_design_F2_v2.md §3.1(DetailManager 상태 부분),
6
7
  * §6.1(masterDetail.maxDepth/expandMultiple 기본값), §6.3(rowExpand/rowCollapse payload)
7
8
  * - docs/design/grid-features-2026-07/15_cross_contracts.md C0.5(범위/선택 정체성 = stable-id 앵커 —
8
9
  * F2 펼침도 동일 원칙), C5.2(이벤트명 `<subject><Verb>` camelCase)
10
+ * / Contract basis:
11
+ * - 11_design_F2_v2.md §3.1 (the state portion of DetailManager), §6.1 (masterDetail.maxDepth/expandMultiple
12
+ * defaults), §6.3 (rowExpand/rowCollapse payload)
13
+ * - 15_cross_contracts.md C0.5 (range/selection identity = stable-id anchors — F2 expansion follows the same
14
+ * principle), C5.2 (event names `<subject><Verb>` camelCase)
9
15
  *
10
16
  * 책임 경계: 이 파일은 **펼침 상태(Set<rowId>)와 규칙**만 다룬다. DOM/서브그리드 생명주기는
11
17
  * SubgridCache, flat 배열 스플라이스는 DetailSplice 가 담당한다(관심사 분리, Booch 경계).
18
+ * / Responsibility boundary: this file handles **only the expansion state (Set<rowId>) and its rules**. DOM /
19
+ * subgrid lifecycle belongs to SubgridCache; flat-array splicing belongs to DetailSplice (separation of concerns).
12
20
  *
13
21
  * ⚠️ FlatRowModel(src/core/FlatRowModel.ts)은 착륙 중인 별도 파일이라 여기서 직접 import 하지 않는다.
14
22
  * rowIndex→rowId 해소는 배선 단계(OpenGrid/DetailManager)에서 FlatRowModel 경유로 수행하고,
15
23
  * 이 클래스는 이미 해소된 stable rowId(string)만 입력받는다.
24
+ * / FlatRowModel (src/core/FlatRowModel.ts) is a separate file still landing, so it is not imported here directly.
25
+ * rowIndex→rowId resolution is done at the wiring stage (OpenGrid/DetailManager) via FlatRowModel; this class only
26
+ * takes already-resolved stable rowIds (string).
16
27
  */
17
- /** FR-6 rowExpand/rowCollapse 이벤트 payload 재료. rowIndex/host 는 배선 단계에서 채운다(§6.3). */
28
+ /** FR-6 rowExpand/rowCollapse 이벤트 payload 재료. rowIndex/host 는 배선 단계에서 채운다(§6.3). / Material for the FR-6 rowExpand/rowCollapse event payload. rowIndex/host are filled at the wiring stage (§6.3). */
18
29
  export interface RowExpandEventPayload {
30
+ /** 대상 행의 flat index. / Flat index of the target row. */
19
31
  rowIndex: number;
32
+ /** 대상 행의 stable rowId. / Stable rowId of the target row. */
20
33
  rowId: string;
34
+ /** 대상 행 데이터. / Target row data. */
21
35
  row: any;
36
+ /** 디테일 패널 host 요소(없으면 null). / Detail panel host element (null if none). */
22
37
  host: HTMLElement | null;
23
38
  }
39
+ /** DetailState 생성 옵션. / DetailState construction options. */
24
40
  export interface DetailStateOptions {
25
- /** masterDetail.maxDepth, 기본 2 (CON-4/FR-10). */
41
+ /** masterDetail.maxDepth, 기본 2 (CON-4/FR-10). / masterDetail.maxDepth, default 2 (CON-4/FR-10). */
26
42
  maxDepth?: number;
27
- /** masterDetail.expandMultiple, 기본 true. false=아코디언(펼침 1개만 허용). */
43
+ /** masterDetail.expandMultiple, 기본 true. false=아코디언(펼침 1개만 허용). / masterDetail.expandMultiple, default true. false = accordion (only one expansion allowed). */
28
44
  expandMultiple?: boolean;
29
- /** 이 그리드 인스턴스의 현재 중첩 깊이(부모가 자식 생성 시 depth+1 주입, CON-4). 기본 0(최상위). */
45
+ /** 이 그리드 인스턴스의 현재 중첩 깊이(부모가 자식 생성 시 depth+1 주입, CON-4). 기본 0(최상위). / Current nesting depth of this grid instance (parent injects depth+1 when creating a child, CON-4). Default 0 (top level). */
30
46
  depth?: number;
31
47
  }
48
+ /** toggle() 결과: 펼침/접힘/거부. / Result of toggle(): expanded / collapsed / rejected. */
32
49
  export type DetailToggleResult = 'expanded' | 'collapsed' | 'rejected';
33
50
  /**
34
51
  * 펼침 상태 보관소. rowId 는 DataLayer stable id(`_ogRowId` 등) — 정렬/필터로 flat 인덱스가
35
52
  * 바뀌어도 이 Set 의 멤버십은 그대로 보존된다(FR-4, C0.5).
53
+ * / Expansion-state store. rowId is a DataLayer stable id (`_ogRowId`, etc.) — even if the flat index changes due
54
+ * to sort/filter, this Set's membership is preserved (FR-4, C0.5).
55
+ *
56
+ * @example
57
+ * const state = new DetailState({ expandMultiple: false });
58
+ * state.toggle('row-7'); // 'expanded'
59
+ * state.isExpanded('row-7'); // true
36
60
  */
37
61
  export declare class DetailState {
38
62
  private _expanded;
39
63
  private _maxDepth;
40
64
  private _expandMultiple;
41
65
  private _depth;
66
+ /**
67
+ * @param opts - maxDepth/expandMultiple/depth 옵션(모두 기본값 있음) / maxDepth/expandMultiple/depth options (all defaulted)
68
+ */
42
69
  constructor(opts?: DetailStateOptions);
43
- /** 읽기 전용 뷰. 소유권은 이 클래스가 유지(외부에서 mutate 금지). */
70
+ /** 읽기 전용 뷰. 소유권은 이 클래스가 유지(외부에서 mutate 금지). / Read-only view. Ownership stays with this class (do not mutate externally). */
44
71
  get expandedRowIds(): ReadonlySet<string>;
72
+ /** 현재 펼쳐진 행 수. / Number of currently expanded rows. */
45
73
  get size(): number;
74
+ /** 이 그리드 인스턴스의 중첩 깊이. / Nesting depth of this grid instance. */
46
75
  get depth(): number;
76
+ /** 허용 최대 중첩 깊이. / Maximum allowed nesting depth. */
47
77
  get maxDepth(): number;
78
+ /** 다중 펼침 허용 여부(false=아코디언). / Whether multiple expansions are allowed (false = accordion). */
48
79
  get expandMultiple(): boolean;
80
+ /**
81
+ * rowId 가 펼쳐져 있는지 여부. / Whether the given rowId is expanded.
82
+ * @param rowId - stable rowId / stable rowId
83
+ * @returns 펼침 여부 / Whether expanded
84
+ */
49
85
  isExpanded(rowId: string): boolean;
50
- /** CON-4/FR-10: depth >= maxDepth 면 이 그리드에서는 더 이상 펼칠 수 없다(중첩 깊이 경계). */
86
+ /**
87
+ * CON-4/FR-10: depth >= maxDepth 면 이 그리드에서는 더 이상 펼칠 수 없다(중첩 깊이 경계).
88
+ * / CON-4/FR-10: if depth >= maxDepth this grid can no longer expand (nesting-depth boundary).
89
+ * @returns 이 깊이에서 펼침 가능 여부 / Whether expansion is possible at this depth
90
+ */
51
91
  canExpand(): boolean;
52
92
  /**
53
- * rowId 를 펼침 상태로 표시.
93
+ * rowId 를 펼침 상태로 표시. / Mark a rowId as expanded.
54
94
  * - depth 초과(EC-6/FR-10)면 false 반환(거부) — 호출자가 announce() 등 경고를 낸다.
55
95
  * - 이미 펼쳐져 있으면 멱등(true, 재적용 없음 — EC-7 빠른 토글 연타 방어).
56
96
  * - expandMultiple:false(아코디언)면 기존 펼침을 전부 접고 이 rowId 만 남긴다.
97
+ * / - Over depth (EC-6/FR-10) returns false (rejected) — the caller emits a warning such as announce().
98
+ * / - If already expanded it is idempotent (true, no re-application — EC-7 defends against rapid toggle spamming).
99
+ * / - When expandMultiple:false (accordion), collapses all existing expansions and keeps only this rowId.
100
+ *
101
+ * @param rowId - stable rowId / stable rowId
102
+ * @returns 펼침 성공 여부(거부 시 false) / Whether expansion succeeded (false when rejected)
57
103
  */
58
104
  expand(rowId: string): boolean;
59
- /** rowId 를 접음. 이미 접혀 있었으면 false(no-op 신호, 호출자가 이벤트 emit 여부 판단). */
105
+ /**
106
+ * rowId 를 접음. 이미 접혀 있었으면 false(no-op 신호, 호출자가 이벤트 emit 여부 판단).
107
+ * / Collapse a rowId. Returns false if it was already collapsed (a no-op signal; the caller decides whether to emit).
108
+ * @param rowId - stable rowId / stable rowId
109
+ * @returns 실제로 접혔는지 여부 / Whether it was actually collapsed
110
+ */
60
111
  collapse(rowId: string): boolean;
61
- /** 토글 1회 = 정확히 하나의 결과(FR-6 "emit 정확히 1회"의 기반). */
112
+ /**
113
+ * 토글 1회 = 정확히 하나의 결과(FR-6 "emit 정확히 1회"의 기반).
114
+ * / One toggle = exactly one result (the basis of FR-6 "emit exactly once").
115
+ * @param rowId - stable rowId / stable rowId
116
+ * @returns 'expanded' | 'collapsed' | 'rejected'
117
+ */
62
118
  toggle(rowId: string): DetailToggleResult;
63
- /** collapseAllDetails() 배선용. 접힌 rowId 목록을 반환(호출자가 각각 rowCollapse emit 판단). */
119
+ /**
120
+ * collapseAllDetails() 배선용. 접힌 rowId 목록을 반환(호출자가 각각 rowCollapse emit 판단).
121
+ * / For wiring collapseAllDetails(). Returns the list of collapsed rowIds (the caller decides whether to emit
122
+ * rowCollapse for each).
123
+ * @returns 접힌 rowId 배열 / Array of collapsed rowIds
124
+ */
64
125
  collapseAll(): string[];
65
- /** FR-6 payload 조립 헬퍼(순수 데이터 조립, emit 자체는 배선 단계 EventEmitter 몫). */
126
+ /**
127
+ * FR-6 payload 조립 헬퍼(순수 데이터 조립, emit 자체는 배선 단계 EventEmitter 몫).
128
+ * / FR-6 payload assembly helper (pure data assembly; the emit itself belongs to the wiring-stage EventEmitter).
129
+ * @param rowId - stable rowId / stable rowId
130
+ * @param rowIndex - 대상 행 flat index / Target row flat index
131
+ * @param row - 대상 행 데이터 / Target row data
132
+ * @param host - 디테일 패널 host(없으면 null) / Detail panel host (null if none)
133
+ * @returns rowExpand/rowCollapse 이벤트 payload / rowExpand/rowCollapse event payload
134
+ */
66
135
  buildEventPayload(rowId: string, rowIndex: number, row: any, host: HTMLElement | null): RowExpandEventPayload;
67
136
  }
@@ -1,10 +1,15 @@
1
1
  /**
2
2
  * SubgridCache — F2 임베드 서브그리드(디테일 인스턴스) 생명주기 관리 (헤드리스, DOM 비접촉).
3
+ * / SubgridCache — lifecycle management for F2 embedded subgrids (detail instances) (headless, no DOM contact).
3
4
  *
4
5
  * 계약 근거:
5
6
  * - docs/design/grid-features-2026-07/11_design_F2_v2.md §3.1(DetailEntry: host/instance/built),
6
7
  * §5(Mount-once + detached 캐시 + 편집중 skip-rebuild — MCCONNELL-04 해소),
7
8
  * §5(5)(collapse: cache!==true 면 destroy, cache:true 면 host 캐시 유지)
9
+ * / Contract basis:
10
+ * - 11_design_F2_v2.md §3.1 (DetailEntry: host/instance/built), §5 (mount-once + detached cache +
11
+ * skip-rebuild while editing — resolves review item MCCONNELL-04), §5(5) (collapse: destroy when cache!==true,
12
+ * keep host cached when cache:true)
8
13
  *
9
14
  * 핵심 의미론(§5 "핵심 통찰"): `_body.innerHTML=''`(GridRenderer 매 렌더 teardown, CON-2)는
10
15
  * "삭제"가 아니라 "분리"다. 이 클래스는 그 통찰을 **mount-once ≠ detach ≠ delete** 3단계로
@@ -12,62 +17,119 @@
12
17
  * 1) mount-once — rowId 당 `adapter.create` 는 정확히 1회만 호출(getOrCreate).
13
18
  * 2) detach/reattach — 매 렌더 teardown/재조립을 생존(파괴 아님, DOM 이동일 뿐).
14
19
  * 3) destroy — collapse(cache:false) 또는 그리드 destroy 시에만 실제 정리.
20
+ * / Core semantics (§5 "key insight"): `_body.innerHTML=''` (GridRenderer teardown every render, CON-2) is
21
+ * "detach", not "delete". This class models that insight as three stages **mount-once ≠ detach ≠ delete**:
22
+ * 1) mount-once — `adapter.create` is called exactly once per rowId (getOrCreate).
23
+ * 2) detach/reattach — survives every-render teardown/reassembly (not destruction, just DOM movement).
24
+ * 3) destroy — real cleanup only on collapse(cache:false) or grid destroy.
15
25
  *
16
26
  * 이 클래스는 DOM 을 직접 만들거나 조작하지 않는다 — 호스트 생성(`hostFactory`)과 실제 마운트/해제
17
27
  * 동작은 전부 `SubgridAdapter` 주입 인터페이스 뒤로 위임한다(렌더 배선 단계가 실 DOM/자식 OpenGrid를
18
28
  * 연결). §5(4) 편집중 skip-rebuild 훅 자리는 `isEditing()` 로 자리만 마련해 둔다(Phase1 배선 대상).
29
+ * / This class never creates or manipulates DOM directly — host creation (`hostFactory`) and the actual
30
+ * mount/unmount actions are all delegated behind the injected `SubgridAdapter` interface (the render-wiring stage
31
+ * connects real DOM / child OpenGrid). The §5(4) skip-rebuild-while-editing hook slot is only stubbed via
32
+ * `isEditing()` (a Phase-1 wiring target).
19
33
  */
20
- /** 서브그리드(또는 임의 렌더러 산출물) 생명주기 훅 — DOM 조작은 이 어댑터 구현체 책임. */
34
+ /** 서브그리드(또는 임의 렌더러 산출물) 생명주기 훅 — DOM 조작은 이 어댑터 구현체 책임. / Lifecycle hooks for a subgrid (or any renderer output) — DOM manipulation is this adapter implementation's responsibility. */
21
35
  export interface SubgridAdapter<T = any> {
22
- /** rowId 당 정확히 1회 호출(§5 mount-once). host 는 영속 div(재렌더 생존, DetailManager.getDetailHost 산출물). */
36
+ /** rowId 당 정확히 1회 호출(§5 mount-once). host 는 영속 div(재렌더 생존, DetailManager.getDetailHost 산출물). / Called exactly once per rowId (§5 mount-once). host is a persistent div (survives re-render, output of DetailManager.getDetailHost). */
23
37
  create(rowId: string, host: HTMLElement): T;
24
- /** teardown 직전: host 를 문서에서 분리하되 instance 는 파괴하지 않는다(§5 "분리≠삭제"). */
38
+ /** teardown 직전: host 를 문서에서 분리하되 instance 는 파괴하지 않는다(§5 "분리≠삭제"). / Just before teardown: detach the host from the document but do not destroy the instance (§5 "detach ≠ delete"). */
25
39
  detach(instance: T, host: HTMLElement): void;
26
- /** 재조립 시: 동일 host/instance 를 새 패널 wrapper 에 재부착. */
40
+ /** 재조립 시: 동일 host/instance 를 새 패널 wrapper 에 재부착. / On reassembly: reattach the same host/instance to the new panel wrapper. */
27
41
  reattach(instance: T, host: HTMLElement): void;
28
- /** collapse(cache:false) 또는 그리드 destroy 시에만 호출 — 실제 정리(EC-9). */
42
+ /** collapse(cache:false) 또는 그리드 destroy 시에만 호출 — 실제 정리(EC-9). / Called only on collapse(cache:false) or grid destroy — real cleanup (EC-9). */
29
43
  destroy(instance: T, host: HTMLElement): void;
30
44
  }
45
+ /** remove() 정책 옵션. / Policy options for remove(). */
31
46
  export interface RemoveOptions {
32
- /** masterDetail.cache. true 면 destroy 대신 detach 만 하고 entry 를 유지(재펼침 시 재사용, §5(5)). */
47
+ /** masterDetail.cache. true 면 destroy 대신 detach 만 하고 entry 를 유지(재펼침 시 재사용, §5(5)). / masterDetail.cache. When true, only detaches (no destroy) and keeps the entry for reuse on re-expand (§5(5)). */
33
48
  cache?: boolean;
34
49
  }
50
+ /**
51
+ * rowId → 디테일 인스턴스/host 캐시. mount-once/detach/destroy 3단계 생명주기를 강제한다.
52
+ * / rowId → detail instance/host cache. Enforces the three-stage mount-once/detach/destroy lifecycle.
53
+ *
54
+ * @typeParam T - 서브그리드 인스턴스 타입 / Subgrid instance type
55
+ */
35
56
  export declare class SubgridCache<T = any> {
36
57
  private adapter;
37
58
  private _entries;
59
+ /**
60
+ * @param adapter - 실제 DOM 마운트/해제를 담당하는 어댑터 / Adapter responsible for the actual DOM mount/unmount
61
+ */
38
62
  constructor(adapter: SubgridAdapter<T>);
63
+ /** 캐시된 entry 수. / Number of cached entries. */
39
64
  get size(): number;
65
+ /**
66
+ * rowId 에 대한 entry 존재 여부. / Whether an entry exists for the rowId.
67
+ * @param rowId - stable rowId / stable rowId
68
+ * @returns entry 존재 여부 / Whether an entry exists
69
+ */
40
70
  has(rowId: string): boolean;
41
71
  /**
42
72
  * 최초 펼침: `hostFactory()` 로 영속 host 를 만들고 `adapter.create` 를 **정확히 1회** 호출한다.
43
73
  * 이미 캐시돼 있으면(재펼침, cache:true 로 남아있던 entry) 기존 entry 를 그대로 반환 — create
44
74
  * 재호출 없음(mount-once 보장의 핵심 단언 지점).
75
+ * / First expand: creates a persistent host via `hostFactory()` and calls `adapter.create` **exactly once**.
76
+ * If already cached (re-expand, an entry kept via cache:true) returns the existing entry as-is — no create
77
+ * re-call (the key assertion point of the mount-once guarantee).
78
+ *
79
+ * @param rowId - stable rowId / stable rowId
80
+ * @param hostFactory - 영속 host 요소 생성 팩토리 / Factory that creates the persistent host element
81
+ * @returns { host, instance } 쌍 / The { host, instance } pair
45
82
  */
46
83
  getOrCreate(rowId: string, hostFactory: () => HTMLElement): {
47
84
  host: HTMLElement;
48
85
  instance: T;
49
86
  };
50
- /** 매 renderBody 재조립 시: 이미 분리돼 있던 entry 만 재부착(파괴됐던 적 없음, §5 핵심 통찰). */
87
+ /**
88
+ * 매 renderBody 재조립 시: 이미 분리돼 있던 entry 만 재부착(파괴됐던 적 없음, §5 핵심 통찰).
89
+ * / On each renderBody reassembly: reattach only entries that were detached (never destroyed, §5 key insight).
90
+ * @param rowId - stable rowId / stable rowId
91
+ * @returns 재부착이 실제로 일어났는지 여부 / Whether a reattach actually occurred
92
+ */
51
93
  reattach(rowId: string): boolean;
52
- /** teardown 직전 분리 표시. entry 는 Map 에 남아 GC 되지 않는다(참조 유지 = 생존, §5 핵심 통찰). */
94
+ /**
95
+ * teardown 직전 분리 표시. entry 는 Map 에 남아 GC 되지 않는다(참조 유지 = 생존, §5 핵심 통찰).
96
+ * / Mark as detached just before teardown. The entry remains in the Map and is not GC'd (keeping the reference = survival, §5 key insight).
97
+ * @param rowId - stable rowId / stable rowId
98
+ * @returns 분리가 실제로 일어났는지 여부 / Whether a detach actually occurred
99
+ */
53
100
  detach(rowId: string): boolean;
54
- /** 부모 renderBody 진입 시 전체 teardown 흉내(호출자가 skip-rebuild 대상은 미리 걸러 호출). */
101
+ /** 부모 renderBody 진입 시 전체 teardown 흉내(호출자가 skip-rebuild 대상은 미리 걸러 호출). / Mimic a full teardown on parent renderBody entry (the caller pre-filters skip-rebuild targets before calling). */
55
102
  detachAll(): void;
56
103
  /**
57
104
  * collapse 시 정책 분기(§5(5)): `cache:true` 면 destroy 없이 detach 만(재펼침 시 getOrCreate 가
58
105
  * 재사용). 기본(`cache` 미지정/false)이면 `adapter.destroy` 후 entry 제거(EC-9 누수 차단).
106
+ * / Policy branch on collapse (§5(5)): with `cache:true`, only detaches without destroy (getOrCreate reuses it on
107
+ * re-expand). By default (`cache` unset/false), calls `adapter.destroy` then removes the entry (EC-9 leak prevention).
108
+ * @param rowId - stable rowId / stable rowId
109
+ * @param opts - cache 유지 여부 옵션 / Option for whether to keep the cache
59
110
  */
60
111
  remove(rowId: string, opts?: RemoveOptions): void;
112
+ /** rowId 의 인스턴스 반환(없으면 undefined). / Return the instance for rowId (undefined if none). */
61
113
  getInstance(rowId: string): T | undefined;
114
+ /** rowId 의 host 요소 반환(없으면 undefined). / Return the host element for rowId (undefined if none). */
62
115
  getHost(rowId: string): HTMLElement | undefined;
116
+ /** rowId 가 현재 부착 상태인지 여부. / Whether rowId is currently attached. */
63
117
  isAttached(rowId: string): boolean;
64
118
  /**
65
119
  * §5(4) 편집중 skip-rebuild 훅 자리(Phase1, FR-8/NFR-2). 렌더 배선 단계에서 자식 인스턴스가
66
120
  * `isEditing()` 같은 판정을 노출하면 `isEditingFn` 으로 주입해 teardown 대상에서 제외(hoist)할지
67
121
  * 판단하는 데 쓴다. 헤드리스 단계에서는 판정 위임만 제공하고 실제 hoist/원복 로직은 GridRenderer
68
122
  * 배선이 담당한다.
123
+ * / §5(4) skip-rebuild-while-editing hook slot (Phase 1, FR-8/NFR-2). At the render-wiring stage, if the child
124
+ * instance exposes a predicate like `isEditing()`, inject it via `isEditingFn` to decide whether to exclude
125
+ * (hoist) it from teardown. In the headless stage this only provides predicate delegation; the actual
126
+ * hoist/restore logic belongs to the GridRenderer wiring.
127
+ *
128
+ * @param rowId - stable rowId / stable rowId
129
+ * @param isEditingFn - 인스턴스 편집중 판정 콜백(미주입 시 항상 false) / Callback deciding whether the instance is editing (always false if not injected)
130
+ * @returns 편집중 여부 / Whether it is editing
69
131
  */
70
132
  isEditing(rowId: string, isEditingFn?: (instance: T) => boolean): boolean;
71
- /** 부모 destroy(EC-9) 또는 collapseAllDetails 시: 남은 전 인스턴스 정리, 누수 차단. */
133
+ /** 부모 destroy(EC-9) 또는 collapseAllDetails 시: 남은 전 인스턴스 정리, 누수 차단. / On parent destroy (EC-9) or collapseAllDetails: clean up all remaining instances, prevent leaks. */
72
134
  destroyAll(): void;
73
135
  }
@@ -1,12 +1,20 @@
1
1
  /**
2
2
  * src/core/detail — F2 마스터/디테일 헤드리스 코어 배럴.
3
+ * / src/core/detail — barrel for the F2 master/detail headless core.
4
+ *
3
5
  * 계약: docs/design/grid-features-2026-07/11_design_F2_v2.md, 15_cross_contracts.md
6
+ * / Contracts: 11_design_F2_v2.md, 15_cross_contracts.md
4
7
  *
5
8
  * 후속 배선(미포함, 이 디렉터리 범위 밖):
6
9
  * - GridRenderer.renderBody 의 `_isDetailHead`/`_isDetailFiller` 분기 + full-width 패널 절대배치
7
10
  * - VirtualScroll.setTotalRows 에 detail 슬롯 반영(spliceDetails 결과 길이)
8
11
  * - FlatRowModel.registerSplice(spliceDetails 어댑터) 연결
9
12
  * - OpenGrid 의 expander 셀 렌더(DetailGlyph 소비) + expandRow/collapseRow/toggleRow API 배선
13
+ * / Downstream wiring (not included, outside this directory's scope):
14
+ * - GridRenderer.renderBody `_isDetailHead`/`_isDetailFiller` branching + absolute-positioned full-width panels
15
+ * - Reflecting detail slots into VirtualScroll.setTotalRows (length of the spliceDetails result)
16
+ * - Connecting FlatRowModel.registerSplice (the spliceDetails adapter)
17
+ * - OpenGrid expander-cell rendering (consuming DetailGlyph) + expandRow/collapseRow/toggleRow API wiring
10
18
  */
11
19
  export * from './DetailState.js';
12
20
  export * from './DetailSplice.js';
@@ -0,0 +1,54 @@
1
+ import { DomainValue, DomainValueDTO } from './DomainValue.js';
2
+ import { ValueType } from './ValueType.js';
3
+ /** 집계 함수 이름. / Aggregation function name. */
4
+ export type AggregateFn = 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'COUNT' | 'WMEAN' | (string & {});
5
+ /** 결측 처리 방식. / Missing-handling mode. */
6
+ export type MissingHandling = 'excluded' | 'included';
7
+ /** 모집단 스코프. / Population scope. */
8
+ export type Population = 'all' | 'filtered' | 'visible' | 'selection';
9
+ /**
10
+ * 집계 결과(REQ-T2-806) — 문맥(함수·표본수·단위·결측처리·모집단)을 함께 고지.
11
+ * / Aggregate result carrying its computation context.
12
+ */
13
+ export interface AggregateResult extends DomainValue {
14
+ readonly fn: AggregateFn;
15
+ readonly value: DomainValue;
16
+ readonly n: number;
17
+ readonly unit: string;
18
+ readonly missingHandling: MissingHandling;
19
+ readonly population: Population;
20
+ }
21
+ /** AggregateResult 구성 인자. / Fields to construct an aggregate result. */
22
+ export interface AggregateResultInit {
23
+ fn: AggregateFn;
24
+ value: DomainValue;
25
+ n: number;
26
+ unit: string;
27
+ missingHandling: MissingHandling;
28
+ population: Population;
29
+ }
30
+ /**
31
+ * 기본 집계 결과 구현. / Concrete aggregate-result value object.
32
+ */
33
+ export declare class BasicAggregateResult implements AggregateResult {
34
+ readonly kind = "aggregate";
35
+ readonly fn: AggregateFn;
36
+ readonly value: DomainValue;
37
+ readonly n: number;
38
+ readonly unit: string;
39
+ readonly missingHandling: MissingHandling;
40
+ readonly population: Population;
41
+ private constructor();
42
+ static of(init: AggregateResultInit): BasicAggregateResult;
43
+ get type(): ValueType;
44
+ isMissing(): boolean;
45
+ isError(): boolean;
46
+ isBlank(): boolean;
47
+ equals(other: DomainValue): boolean;
48
+ hashKey(): string;
49
+ compareTo(other: DomainValue): number;
50
+ textEquivalent(locale?: string): string;
51
+ toJSON(): DomainValueDTO;
52
+ }
53
+ /** AggregateResult 값 타입. / ValueType for aggregate. */
54
+ export declare const aggregateType: ValueType;