open-grid 1.2.1 → 1.3.1

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 (258) hide show
  1. package/CHANGELOG.md +388 -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/FilterSelect.d.ts +26 -5
  25. package/dist/types/core/FormulaEngine.d.ts +15 -4
  26. package/dist/types/core/GridRenderer.d.ts +143 -10
  27. package/dist/types/core/GridShuttle.d.ts +26 -10
  28. package/dist/types/core/GroupEngine.d.ts +68 -10
  29. package/dist/types/core/IconRegistry.d.ts +31 -13
  30. package/dist/types/core/MathUtils.d.ts +58 -5
  31. package/dist/types/core/MergeEngine.d.ts +45 -10
  32. package/dist/types/core/OGDecimal.d.ts +144 -13
  33. package/dist/types/core/OpenGrid.d.ts +401 -122
  34. package/dist/types/core/OrgChart.d.ts +32 -11
  35. package/dist/types/core/PivotEngine.d.ts +37 -0
  36. package/dist/types/core/RowDragDrop.d.ts +52 -6
  37. package/dist/types/core/SkinRegistry.d.ts +86 -19
  38. package/dist/types/core/TreeEngine.d.ts +60 -6
  39. package/dist/types/core/VirtualScroll.d.ts +64 -0
  40. package/dist/types/core/XmlConverter.d.ts +40 -0
  41. package/dist/types/core/a11y/AccessibilityAdapter.d.ts +103 -0
  42. package/dist/types/core/a11y/AriaIntent.d.ts +34 -0
  43. package/dist/types/core/a11y/KeyboardInteractionModel.d.ts +64 -0
  44. package/dist/types/core/a11y/LiveRegionController.d.ts +89 -0
  45. package/dist/types/core/a11y/OverlayStack.d.ts +36 -0
  46. package/dist/types/core/a11y/VisualEquivRegistry.d.ts +37 -0
  47. package/dist/types/core/a11y/index.d.ts +13 -0
  48. package/dist/types/core/a11y/ports.d.ts +24 -0
  49. package/dist/types/core/appearance/Appearance.d.ts +68 -0
  50. package/dist/types/core/appearance/AppearanceAxis.d.ts +94 -0
  51. package/dist/types/core/appearance/AppearanceComposer.d.ts +45 -0
  52. package/dist/types/core/appearance/AppearanceProvider.d.ts +50 -0
  53. package/dist/types/core/appearance/AppearanceView.d.ts +51 -0
  54. package/dist/types/core/appearance/DensityRegistry.d.ts +36 -0
  55. package/dist/types/core/appearance/ResolvedAppearanceSnapshot.d.ts +84 -0
  56. package/dist/types/core/appearance/TextureRegistry.d.ts +32 -0
  57. package/dist/types/core/appearance/ThemeMetaRegistry.d.ts +67 -0
  58. package/dist/types/core/appearance/axisAdapters.d.ts +37 -0
  59. package/dist/types/core/appearance/defaults.d.ts +10 -0
  60. package/dist/types/core/appearance/index.d.ts +20 -0
  61. package/dist/types/core/appearance/tokenCatalog.d.ts +30 -0
  62. package/dist/types/core/cf/CFEngine.d.ts +56 -0
  63. package/dist/types/core/cf/CFEvaluator.d.ts +24 -0
  64. package/dist/types/core/cf/CFRule.d.ts +127 -0
  65. package/dist/types/core/cf/ColorScale.d.ts +49 -0
  66. package/dist/types/core/cf/InkResolver.d.ts +33 -0
  67. package/dist/types/core/cf/appearance.d.ts +20 -0
  68. package/dist/types/core/cf/encoders.d.ts +61 -0
  69. package/dist/types/core/cf/eval-types.d.ts +93 -0
  70. package/dist/types/core/cf/index.d.ts +21 -0
  71. package/dist/types/core/cf/lineage.d.ts +32 -0
  72. package/dist/types/core/cf/predicates.d.ts +27 -0
  73. package/dist/types/core/cf/serialize.d.ts +46 -0
  74. package/dist/types/core/chart/CanvasAdapter.d.ts +50 -1
  75. package/dist/types/core/chart/DataExtractor.d.ts +53 -12
  76. package/dist/types/core/chart/a11y.d.ts +22 -0
  77. package/dist/types/core/chart/chart-type-registry.d.ts +53 -0
  78. package/dist/types/core/chart/downsample-report.d.ts +36 -0
  79. package/dist/types/core/chart/downsample.d.ts +26 -1
  80. package/dist/types/core/chart/engine/ChartEngineRegistry.d.ts +52 -0
  81. package/dist/types/core/chart/geometry.d.ts +96 -0
  82. package/dist/types/core/chart/hittest.d.ts +21 -3
  83. package/dist/types/core/chart/palette.d.ts +96 -12
  84. package/dist/types/core/chart/parity.d.ts +12 -0
  85. package/dist/types/core/chart/provenance.d.ts +47 -0
  86. package/dist/types/core/chart/scales.d.ts +28 -1
  87. package/dist/types/core/chart/scene.d.ts +102 -0
  88. package/dist/types/core/chart/server.d.ts +36 -0
  89. package/dist/types/core/chart/surfaces/CanvasSurface.d.ts +48 -0
  90. package/dist/types/core/chart/surfaces/ServerRasterSurface.d.ts +26 -0
  91. package/dist/types/core/chart/surfaces/SvgSurface.d.ts +24 -0
  92. package/dist/types/core/chart/surfaces/pattern-overlay.d.ts +24 -0
  93. package/dist/types/core/chart/types.d.ts +102 -21
  94. package/dist/types/core/command/CommandBus.d.ts +51 -0
  95. package/dist/types/core/command/CommandRegistry.d.ts +43 -0
  96. package/dist/types/core/command/CommandStack.d.ts +38 -0
  97. package/dist/types/core/command/ICommand.d.ts +110 -0
  98. package/dist/types/core/command/commands/CellWriteCommand.d.ts +32 -0
  99. package/dist/types/core/command/commands/CompositeCommand.d.ts +17 -0
  100. package/dist/types/core/command/commands/RowCommands.d.ts +39 -0
  101. package/dist/types/core/command/index.d.ts +9 -0
  102. package/dist/types/core/command/support.d.ts +51 -0
  103. package/dist/types/core/coordinate/ColumnMetrics.d.ts +30 -0
  104. package/dist/types/core/coordinate/CoordinateKernel.d.ts +88 -0
  105. package/dist/types/core/coordinate/FrozenPanes.d.ts +29 -0
  106. package/dist/types/core/coordinate/MergeSourceAdapter.d.ts +18 -0
  107. package/dist/types/core/coordinate/NodeBudget.d.ts +33 -0
  108. package/dist/types/core/coordinate/ResizeGovernor.d.ts +50 -0
  109. package/dist/types/core/coordinate/RowMetrics.d.ts +37 -0
  110. package/dist/types/core/coordinate/ViewPermutation.d.ts +23 -0
  111. package/dist/types/core/coordinate/index.d.ts +10 -0
  112. package/dist/types/core/coordinate/ports.d.ts +45 -0
  113. package/dist/types/core/coordinate/types.d.ts +76 -0
  114. package/dist/types/core/detail/DetailGlyph.d.ts +42 -7
  115. package/dist/types/core/detail/DetailSplice.d.ts +42 -11
  116. package/dist/types/core/detail/DetailState.d.ts +80 -11
  117. package/dist/types/core/detail/SubgridCache.d.ts +72 -10
  118. package/dist/types/core/detail/index.d.ts +8 -0
  119. package/dist/types/core/domain/AggregateResult.d.ts +54 -0
  120. package/dist/types/core/domain/CellAddress.d.ts +61 -0
  121. package/dist/types/core/domain/CellValueAccess.d.ts +29 -0
  122. package/dist/types/core/domain/Delta.d.ts +37 -0
  123. package/dist/types/core/domain/DomainValue.d.ts +80 -0
  124. package/dist/types/core/domain/Missing.d.ts +65 -0
  125. package/dist/types/core/domain/Money.d.ts +42 -0
  126. package/dist/types/core/domain/NormalizationBasis.d.ts +47 -0
  127. package/dist/types/core/domain/Plain.d.ts +45 -0
  128. package/dist/types/core/domain/Quantity.d.ts +32 -0
  129. package/dist/types/core/domain/Ratios.d.ts +100 -0
  130. package/dist/types/core/domain/ThresholdSet.d.ts +46 -0
  131. package/dist/types/core/domain/ValueType.d.ts +71 -0
  132. package/dist/types/core/domain/rounding.d.ts +25 -0
  133. package/dist/types/core/domain/strategies.d.ts +38 -0
  134. package/dist/types/core/editors/DateEditor.d.ts +18 -0
  135. package/dist/types/core/editors/SelectEditor.d.ts +29 -0
  136. package/dist/types/core/export/ChannelRegistry.d.ts +18 -0
  137. package/dist/types/core/export/ExportManifest.d.ts +13 -0
  138. package/dist/types/core/export/GridArtifactSource.d.ts +62 -0
  139. package/dist/types/core/export/Provenance.d.ts +34 -0
  140. package/dist/types/core/export/StreamPump.d.ts +28 -0
  141. package/dist/types/core/export/channels/CsvChannel.d.ts +20 -0
  142. package/dist/types/core/export/channels/JsonChannel.d.ts +18 -0
  143. package/dist/types/core/export/channels/XlsxChannel.d.ts +53 -0
  144. package/dist/types/core/export/channels/XmlChannel.d.ts +21 -0
  145. package/dist/types/core/export/channels/capabilities.d.ts +13 -0
  146. package/dist/types/core/export/index.d.ts +24 -0
  147. package/dist/types/core/export/print/OutputChannelAdapter.d.ts +61 -0
  148. package/dist/types/core/export/print/Paginator.d.ts +48 -0
  149. package/dist/types/core/export/print/PrintRenderTarget.d.ts +36 -0
  150. package/dist/types/core/export/sinks.d.ts +40 -0
  151. package/dist/types/core/export/types.d.ts +211 -0
  152. package/dist/types/core/extension/DeprecationManager.d.ts +42 -0
  153. package/dist/types/core/extension/IExtension.d.ts +90 -0
  154. package/dist/types/core/extension/Registry.d.ts +142 -0
  155. package/dist/types/core/extension/SlotRegistry.d.ts +46 -0
  156. package/dist/types/core/extension/adapters.d.ts +44 -0
  157. package/dist/types/core/extension/conformance.d.ts +47 -0
  158. package/dist/types/core/extension/index.d.ts +16 -0
  159. package/dist/types/core/extension/registries.d.ts +31 -0
  160. package/dist/types/core/extension/reserved.d.ts +10 -0
  161. package/dist/types/core/format/DisplayFormatter.d.ts +47 -0
  162. package/dist/types/core/format/FormatCache.d.ts +20 -0
  163. package/dist/types/core/format/FormatterRegistry.d.ts +22 -0
  164. package/dist/types/core/format/grammar/AstRenderer.d.ts +10 -0
  165. package/dist/types/core/format/grammar/FormatCompiler.d.ts +16 -0
  166. package/dist/types/core/format/index.d.ts +55 -0
  167. package/dist/types/core/format/pipeline/DomainTypeResolver.d.ts +8 -0
  168. package/dist/types/core/format/pipeline/LocaleFormat.d.ts +11 -0
  169. package/dist/types/core/format/pipeline/ValueInterpreter.d.ts +8 -0
  170. package/dist/types/core/format/policy/MaskPolicy.d.ts +8 -0
  171. package/dist/types/core/format/policy/NegativePolicy.d.ts +12 -0
  172. package/dist/types/core/format/policy/NullPolicy.d.ts +10 -0
  173. package/dist/types/core/format/policy/TruncatePolicy.d.ts +11 -0
  174. package/dist/types/core/format/types.d.ts +292 -0
  175. package/dist/types/core/formula/CalcCacheStore.d.ts +89 -0
  176. package/dist/types/core/formula/CalcProvenance.d.ts +44 -0
  177. package/dist/types/core/formula/CalcService.d.ts +137 -0
  178. package/dist/types/core/formula/CyclePathReporter.d.ts +28 -0
  179. package/dist/types/core/formula/FormulaEvaluator.d.ts +35 -1
  180. package/dist/types/core/formula/FormulaGraph.d.ts +84 -7
  181. package/dist/types/core/formula/FormulaParser.d.ts +9 -0
  182. package/dist/types/core/formula/FormulaStore.d.ts +63 -1
  183. package/dist/types/core/formula/FunctionRegistry.d.ts +138 -0
  184. package/dist/types/core/formula/Generation.d.ts +86 -0
  185. package/dist/types/core/formula/RecalcCoordinator.d.ts +151 -9
  186. package/dist/types/core/formula/ReferenceRewriter.d.ts +81 -0
  187. package/dist/types/core/formula/functions/essential.d.ts +3 -0
  188. package/dist/types/core/formula/functions/extended/index.d.ts +10 -0
  189. package/dist/types/core/formula/normalizeRefs.d.ts +34 -3
  190. package/dist/types/core/formula/numericLiteral.d.ts +11 -1
  191. package/dist/types/core/formula/serializeFormula.d.ts +10 -1
  192. package/dist/types/core/host/CapabilityRegistry.d.ts +61 -0
  193. package/dist/types/core/host/GridHostDriver.d.ts +27 -0
  194. package/dist/types/core/host/GridHostPort.d.ts +37 -0
  195. package/dist/types/core/host/SliceOwnershipGuard.d.ts +27 -0
  196. package/dist/types/core/host/archCheck.d.ts +26 -0
  197. package/dist/types/core/host/index.d.ts +6 -0
  198. package/dist/types/core/host/reconcile.d.ts +22 -0
  199. package/dist/types/core/i18n/LocaleContext.d.ts +40 -0
  200. package/dist/types/core/i18n/LocaleRegistry.d.ts +0 -0
  201. package/dist/types/core/i18n/types.d.ts +67 -11
  202. package/dist/types/core/icons/bootstrap-icons.d.ts +4 -2
  203. package/dist/types/core/quality/ContrastAuditor.d.ts +64 -0
  204. package/dist/types/core/quality/DeterminismKernel.d.ts +68 -0
  205. package/dist/types/core/quality/PerfBaseline.d.ts +23 -0
  206. package/dist/types/core/quality/PerfSpec.d.ts +95 -0
  207. package/dist/types/core/quality/RealBrowserGate.d.ts +69 -0
  208. package/dist/types/core/quality/RegressionJudge.d.ts +35 -0
  209. package/dist/types/core/quality/ReleaseGate.d.ts +94 -0
  210. package/dist/types/core/quality/VisualRegression.d.ts +74 -0
  211. package/dist/types/core/quality/hooks.d.ts +53 -0
  212. package/dist/types/core/quality/index.d.ts +20 -0
  213. package/dist/types/core/quality/pixelMetrics.d.ts +24 -0
  214. package/dist/types/core/range/ClipboardCodec.d.ts +46 -4
  215. package/dist/types/core/range/FillEngine.d.ts +69 -9
  216. package/dist/types/core/range/RangeModel.d.ts +100 -13
  217. package/dist/types/core/range/types.d.ts +27 -11
  218. package/dist/types/core/realtime/BackpressureScheduler.d.ts +0 -0
  219. package/dist/types/core/realtime/FreshnessClock.d.ts +34 -0
  220. package/dist/types/core/realtime/IRealtimeSource.d.ts +82 -0
  221. package/dist/types/core/realtime/LiveStateGuard.d.ts +23 -0
  222. package/dist/types/core/realtime/PollingSource.d.ts +42 -0
  223. package/dist/types/core/realtime/RealtimeController.d.ts +54 -0
  224. package/dist/types/core/realtime/RtAnnouncePolicy.d.ts +53 -0
  225. package/dist/types/core/realtime/RtApplyCommand.d.ts +29 -0
  226. package/dist/types/core/realtime/RtChartTargetTrigger.d.ts +26 -0
  227. package/dist/types/core/realtime/StreamingSource.d.ts +47 -0
  228. package/dist/types/core/realtime/backoff.d.ts +12 -0
  229. package/dist/types/core/realtime/index.d.ts +13 -0
  230. package/dist/types/core/realtime/ports.d.ts +80 -0
  231. package/dist/types/core/render/CellApplier.d.ts +18 -0
  232. package/dist/types/core/render/CellErrorBoundary.d.ts +65 -0
  233. package/dist/types/core/render/CellPipeline.d.ts +39 -0
  234. package/dist/types/core/render/CellRenderRequest.d.ts +209 -0
  235. package/dist/types/core/render/CellStageRegistry.d.ts +53 -0
  236. package/dist/types/core/render/OverlayCompositor.d.ts +38 -0
  237. package/dist/types/core/render/RenderBudget.d.ts +67 -0
  238. package/dist/types/core/render/contrast.d.ts +33 -0
  239. package/dist/types/core/render/index.d.ts +35 -0
  240. package/dist/types/core/render/stages/BackgroundStage.d.ts +14 -0
  241. package/dist/types/core/render/stages/DecoratorStage.d.ts +12 -0
  242. package/dist/types/core/render/stages/OverlayStage.d.ts +12 -0
  243. package/dist/types/core/render/stages/ValueRendererStage.d.ts +15 -0
  244. package/dist/types/core/render/stages/index.d.ts +14 -0
  245. package/dist/types/core/state/AutosaveController.d.ts +63 -0
  246. package/dist/types/core/state/IStatePersistence.d.ts +59 -0
  247. package/dist/types/core/state/MultiTabGuard.d.ts +33 -0
  248. package/dist/types/core/state/SchemaMigrator.d.ts +33 -0
  249. package/dist/types/core/state/SemVerPolicy.d.ts +39 -0
  250. package/dist/types/core/state/StateCodec.d.ts +75 -0
  251. package/dist/types/core/state/index.d.ts +6 -0
  252. package/dist/types/core/types.d.ts +511 -226
  253. package/dist/types/react/OpenGrid.d.ts +54 -0
  254. package/dist/types/react/index.d.ts +5 -0
  255. package/dist/types/realtime/index.d.ts +1 -0
  256. package/dist/types/vue/index.d.ts +5 -0
  257. package/dist/types/vue/types.d.ts +35 -0
  258. package/package.json +112 -111
@@ -8,7 +8,10 @@ export interface OrgChartColumnDef {
8
8
  className?: string;
9
9
  /** 인라인 스타일 문자열 또는 (값, 행)→스타일 함수. / Inline style string or (value, row)→style function. */
10
10
  style?: string | ((value: any, row: Record<string, any>) => string);
11
- /** 커스텀 렌더러. 문자열 반환 시 innerHTML, 엘리먼트 반환 시 append. / Custom renderer; a string is set as innerHTML, an element is appended. */
11
+ /** 커스텀 렌더러. 값을 텍스트 그대로 보여주는 대신 아바타·배지·아이콘 같은 커스텀 마크업을
12
+ * 넣고 싶을 때 지정한다. 문자열 반환 시 innerHTML, 엘리먼트 반환 시 append.
13
+ * / Custom renderer. Set this when you need avatars, badges, or icons instead of plain text.
14
+ * A string return is set as innerHTML; an element return is appended. */
12
15
  renderer?: (value: any, row: Record<string, any>) => HTMLElement | string;
13
16
  }
14
17
  /**
@@ -37,10 +40,17 @@ export interface OrgChartOptions {
37
40
  /**
38
41
  * 조직도 컴포넌트. / Org-chart component.
39
42
  *
40
- * 부모/자식 관계(idField/parentIdField)를 가진 평면 데이터를 트리로 구성해
41
- * SVG 연결선 + 노드 카드로 렌더한다. 그리드와 독립된 standalone 컴포넌트다.
42
- * / Builds a tree from flat parent/child data (idField/parentIdField) and renders it as
43
- * SVG connectors plus node cards. A standalone component independent of the grid.
43
+ * 보고 라인·조직 구조·계층형 카테고리처럼 "누가 누구 밑에 있는가"를 시각적으로 보여주고 싶을 때
44
+ * 쓴다. 그리드와 별개의 독립 컴포넌트라서, 그리드 없이 조직도 하나만 페이지에 넣어도 동작한다.
45
+ * 동작 순서: `setData()`로 평면 행 배열(각 행에 id/parentId만 있으면 됨)을 넘기면 → 내부에서
46
+ * 부모/자식 관계(idField/parentIdField)를 따라 트리로 구성하고 → 그 결과를 SVG 연결선 + 노드
47
+ * 카드로 화면에 그린다.
48
+ * / Use this when you need to show "who reports to whom" — org structure, reporting lines, or
49
+ * hierarchical categories. It's a standalone component independent of the grid, so it works on
50
+ * its own with no grid on the page. Operation order: pass a flat row array to `setData()` (each
51
+ * row just needs an id/parentId) → internally it's built into a tree following the parent/child
52
+ * relation (idField/parentIdField) → the result is drawn on screen as SVG connectors plus node
53
+ * cards.
44
54
  *
45
55
  * @example
46
56
  * const chart = new OrgChart('#org', {
@@ -62,27 +72,38 @@ export declare class OrgChart {
62
72
  */
63
73
  constructor(selector: string | HTMLElement, opts: OrgChartOptions);
64
74
  /**
65
- * 조직도 데이터를 설정하고 렌더한다. / Set org-chart data and render.
75
+ * 조직도 데이터를 설정하고 렌더한다. 최초 로드는 물론, 데이터를 새로 받아올 때마다
76
+ * 다시 호출하면 트리를 재구성해 다시 그린다. / Set org-chart data and render. Call this on
77
+ * initial load and again whenever fresh data arrives — it rebuilds the tree and redraws.
66
78
  *
67
79
  * @param data - 부모/자식 관계를 가진 평면 행 배열 / Flat array of rows with parent/child relations
68
80
  */
69
81
  setData(data: Record<string, any>[]): void;
70
82
  /**
71
- * COLOR 축 테마를 컨테이너에 설정한다. / Set the COLOR-axis theme on the container.
83
+ * 색 테마(라이트/다크 등)를 컨테이너에 설정한다. 호스트 페이지의 다크모드 토글에 맞춰 전환할
84
+ * 때 호출한다. / Set the color theme (light/dark, etc.) on the container. Call this when
85
+ * switching to match the host page's dark-mode toggle.
72
86
  *
73
87
  * @param theme - data-og-theme 값 / data-og-theme value
74
88
  */
75
89
  setTheme(theme: string): void;
76
90
  /**
77
- * R12b: FORM(스킨) 축 — data-og-skin 을 자기 컨테이너에 설정(setTheme 과 동형, 색과 직교).
78
- * / R12b: FORM (skin) axis — set data-og-skin on the container (symmetric to setTheme, orthogonal to color).
91
+ * 형태(스킨) 테마를 컨테이너에 설정한다. 색은 그대로 두고 모서리·밀도 같은 겉모양만 바꾸고
92
+ * 싶을 때 쓴다. `setTheme`(색)과 서로 독립된 축이라, 색 테마는 그대로 두고 스킨만 바꾸거나
93
+ * 그 반대로 자유롭게 조합할 수 있다.
94
+ * / Set the form (skin) theme on the container. Use this to change the look (corner radius,
95
+ * density, etc.) while leaving color untouched. This is an axis independent from `setTheme`
96
+ * (color), so you can swap the skin alone, the color theme alone, or both freely.
79
97
  *
80
98
  * @param skin - data-og-skin 값 / data-og-skin value
81
99
  */
82
100
  setSkin(skin: string): void;
83
- /** 모든 노드를 펼친다. / Expand all nodes. */
101
+ /** 모든 노드를 펼친다. 조직 전체를 한눈에 훑어보고 싶을 때 호출. / Expand all nodes. Call when
102
+ * the viewer wants to see the whole organization at a glance. */
84
103
  expandAll(): void;
85
- /** 모든 노드를 접는다(루트만 표시). / Collapse all nodes (roots only). */
104
+ /** 모든 노드를 접는다(루트만 표시). 큰 조직도를 처음 접했을 때 최상위 구조부터 보여주고 싶을
105
+ * 때 호출. / Collapse all nodes (roots only). Call to show top-level structure first when a
106
+ * large org chart is first opened. */
86
107
  collapseAll(): void;
87
108
  private _toggle;
88
109
  private _rebuild;
@@ -1,18 +1,55 @@
1
1
  import { ColumnDef } from './types.js';
2
+ /** 피벗 집계 방식. / Pivot aggregation method. */
2
3
  export type PivotAgg = 'SUM' | 'COUNT' | 'AVG' | 'MIN' | 'MAX';
4
+ /** 피벗 연산 설정. / Pivot computation configuration. */
3
5
  export interface PivotConfig {
6
+ /** 행 축 필드명 목록. / Row-axis field names. */
4
7
  rowFields: string[];
8
+ /** 열 축 필드명 목록. / Column-axis field names. */
5
9
  colFields: string[];
10
+ /** 집계 대상 값 필드 목록. / Value fields to aggregate. */
6
11
  valueFields: string[];
12
+ /** 집계 방식(기본 SUM). / Aggregation method (default SUM). */
7
13
  agg?: PivotAgg;
14
+ /** 숫자 포맷 패턴. / Number format pattern. */
8
15
  format?: string;
9
16
  }
17
+ /** 피벗 연산 결과 — OpenGrid 에 바로 바인딩 가능. / Pivot result — directly bindable to OpenGrid. */
10
18
  export interface PivotResult {
19
+ /** 생성된 컬럼 정의(행 축 + 동적 값 컬럼). / Generated column defs (row axis + dynamic value columns). */
11
20
  columns: ColumnDef[];
21
+ /** 피벗 데이터 행(합계 행 포함 가능). / Pivot data rows (may include a totals row). */
12
22
  data: any[];
23
+ /** 동적 컬럼 키 조합 목록(UI 참조용). / Dynamic column key combinations (for UI reference). */
13
24
  colKeys: string[][];
14
25
  }
26
+ /**
27
+ * 피벗 테이블 연산 엔진(레이어: Algorithm, 순수 함수). / Pivot-table computation engine (layer: Algorithm, pure function).
28
+ *
29
+ * 행/열/값 필드를 지정하면 데이터를 교차 집계하여 OpenGrid 에 바로 바인딩 가능한 columns+data 를 반환한다.
30
+ * / Given row/column/value fields, cross-aggregates the data and returns columns+data that bind
31
+ * directly to OpenGrid.
32
+ *
33
+ * @example
34
+ * const result = new PivotEngine().compute(rows, {
35
+ * rowFields: ['region'], colFields: ['quarter'], valueFields: ['amount'], agg: 'SUM',
36
+ * });
37
+ * grid.setColumns(result.columns); grid.setData(result.data);
38
+ */
15
39
  export declare class PivotEngine {
40
+ /**
41
+ * 피벗 연산 실행 — 교차 집계 columns+data 생성. / Run the pivot — produces cross-aggregated columns+data.
42
+ *
43
+ * 열 축 유니크 값의 카르테시안 곱으로 동적 컬럼을 만들고, 행 축으로 그룹화해 집계한다.
44
+ * 결과 행이 2개 이상이면 총계 행을 덧붙인다(총계 라벨은 전역 로케일로 해석).
45
+ * / Builds dynamic columns from the Cartesian product of column-axis unique values, groups by the
46
+ * row axis, and aggregates. Appends a totals row when more than one result row exists (the
47
+ * totals label is resolved via the global locale).
48
+ *
49
+ * @param data - 원본 행 배열 / Source rows
50
+ * @param config - 행/열/값 필드 및 집계 설정 / Row/column/value fields and aggregation settings
51
+ * @returns 컬럼·데이터·컬럼키 조합 / Columns, data, and column-key combinations
52
+ */
16
53
  compute(data: any[], config: PivotConfig): PivotResult;
17
54
  private _cartesian;
18
55
  private _aggregate;
@@ -1,38 +1,84 @@
1
+ /**
2
+ * 행 재정렬이 확정됐을 때 호출되는 콜백. / Callback fired when a row reorder is committed.
3
+ *
4
+ * @param fromIndex - 이동 전 행의 flat index / Flat index of the row before the move
5
+ * @param toIndex - 이동 후 삽입 위치 flat index / Flat index of the insertion position after the move
6
+ */
1
7
  export type RowDropCallback = (fromIndex: number, toIndex: number) => void;
2
- /** 커서 좌표로 다른 그리드의 바디를 찾는 해석기 */
8
+ /** 커서 좌표로 다른 그리드의 바디를 찾는 해석기의 결과. / Result of resolving another grid's body from cursor coordinates. */
3
9
  export interface CrossGridResolveResult {
10
+ /** 대상 그리드의 바디 요소. / Body element of the target grid. */
4
11
  bodyEl: HTMLElement;
12
+ /** 대상 그리드의 행 높이(px). / Row height of the target grid (px). */
5
13
  rowHeight: number;
14
+ /** 대상 그리드의 전체 행 수. / Total number of rows in the target grid. */
6
15
  totalRows: number;
7
16
  }
17
+ /**
18
+ * 그리드 간 드래그(crossGrid) 판정을 주입하는 설정.
19
+ * / Configuration that injects cross-grid drag resolution.
20
+ */
8
21
  export interface CrossGridConfig {
9
- /** 커서 위치(x,y)에 있는 다른(crossGrid 허용) 그리드 바디 정보 반환. 없으면 null */
22
+ /**
23
+ * 커서 위치(x,y)에 있는 다른(crossGrid 허용) 그리드 바디 정보 반환. 없으면 null.
24
+ * / Return the body info of another (crossGrid-enabled) grid at cursor position (x,y); null if none.
25
+ *
26
+ * @param clientX - 커서 X(clientX) / Cursor X (clientX)
27
+ * @param clientY - 커서 Y(clientY) / Cursor Y (clientY)
28
+ * @returns 대상 그리드 정보 또는 null / Target grid info, or null
29
+ */
10
30
  resolveTarget: (clientX: number, clientY: number) => CrossGridResolveResult | null;
11
- /** 다른 그리드로 드롭됐을 때 호출 (소스 fromIndex, 타깃 바디, 타깃 삽입 인덱스) */
31
+ /**
32
+ * 다른 그리드로 드롭됐을 때 호출 (소스 fromIndex, 타깃 바디, 타깃 삽입 인덱스).
33
+ * / Called when dropped onto another grid (source fromIndex, target body, target insertion index).
34
+ *
35
+ * @param fromIndex - 소스 그리드에서의 행 flat index / Row flat index in the source grid
36
+ * @param targetBodyEl - 드롭 대상 그리드의 바디 / Body of the drop target grid
37
+ * @param targetIndex - 대상 그리드의 삽입 인덱스 / Insertion index in the target grid
38
+ */
12
39
  onCrossDrop: (fromIndex: number, targetBodyEl: HTMLElement, targetIndex: number) => void;
13
40
  }
14
41
  /**
15
42
  * 행 드래그앤드롭 관리자 (순수 DnD).
16
43
  * 행 DOM에 드래그 핸들을 심고, 고스트/인디케이터로 위치를 표시한 뒤 콜백으로 알림.
17
44
  * 그리드 간 이동 판정(타깃 그리드 해석)은 주입된 CrossGridConfig 에 위임한다.
45
+ * / Row drag-and-drop manager (pure DnD).
46
+ * Plants a drag handle into row DOM, shows position via ghost/indicator, then notifies through
47
+ * callbacks. Cross-grid move resolution (target grid lookup) is delegated to the injected
48
+ * CrossGridConfig.
49
+ *
50
+ * @param _bodyEl - 이 관리자가 담당하는 그리드 바디 / Grid body this manager owns
51
+ * @param _rowHeight - 행 높이(px) / Row height (px)
52
+ * @param _onDrop - 자기 그리드 내 재정렬 확정 콜백 / Callback for a committed in-grid reorder
53
+ * @param _cross - 그리드 간 드래그 설정(없으면 자기 그리드 내로 제한) / Cross-grid config (null limits to in-grid)
54
+ * @param _getDragCount - fromIndex 기준 함께 드래그할 행 수 계산기(멀티행 배지용) / Computes rows dragged together from fromIndex (for the multi-row badge)
18
55
  */
19
56
  export declare class RowDragDrop {
20
57
  private _bodyEl;
21
58
  private _rowHeight;
22
59
  private _onDrop;
23
60
  private _cross;
24
- /** fromIndex 기준 함께 드래그할 행 수(멀티행 배지용). 기본 1 */
61
+ /** fromIndex 기준 함께 드래그할 행 수(멀티행 배지용). 기본 1 / Rows dragged together from fromIndex (multi-row badge). Default 1 */
25
62
  private _getDragCount;
26
63
  private _drag;
27
64
  private readonly _selfIndicator;
28
65
  private readonly _crossIndicator;
29
66
  constructor(_bodyEl: HTMLElement, _rowHeight: number, _onDrop: RowDropCallback, _cross?: CrossGridConfig | null,
30
- /** fromIndex 기준 함께 드래그할 행 수(멀티행 배지용). 기본 1 */
67
+ /** fromIndex 기준 함께 드래그할 행 수(멀티행 배지용). 기본 1 / Rows dragged together from fromIndex (multi-row badge). Default 1 */
31
68
  _getDragCount?: (fromIndex: number) => number);
32
- /** 행 엘리먼트에 드래그 핸들 삽입 */
69
+ /**
70
+ * 행 엘리먼트에 드래그 핸들 삽입.
71
+ * / Insert a drag handle into a row element.
72
+ *
73
+ * @param rowEl - 핸들을 붙일 행 요소 / Row element to attach the handle to
74
+ * @param rowIndex - 해당 행의 flat index / Flat index of that row
75
+ * @param totalRows - 현재 전체 행 수(경계 클램프용) / Current total row count (for boundary clamping)
76
+ * @returns 생성된 드래그 핸들 요소 / The created drag handle element
77
+ */
33
78
  attachHandle(rowEl: HTMLElement, rowIndex: number, totalRows: number): HTMLElement;
34
79
  private _startDrag;
35
80
  private _onMouseMove;
36
81
  private _onMouseUp;
82
+ /** 전역 리스너 해제 + 진행 중 드래그/인디케이터 정리. / Detach global listeners + clean up any in-progress drag/indicators. */
37
83
  destroy(): void;
38
84
  }
@@ -1,4 +1,17 @@
1
1
  import { SkinTokenDelta } from './types.js';
2
+ /**
3
+ * 스킨(FORM) 델타에 등장할 수 있는 CSS 커스텀 프로퍼티 이름의 허용 목록(런타임 가드).
4
+ * 스킨은 형태(모서리·테두리·그림자·밀도 등)만 다루고 색은 다루지 않는다는 규칙을, 이 목록이
5
+ * 물리적으로 강제한다 — `define()`/`registerBuiltin()` 이 델타를 검사할 때 이 집합에 없는
6
+ * 키는 거부한다. 반대 방향(테마 델타에 형태 토큰이 섞이는 것)도 이 집합을 재사용해 막는다
7
+ * (색⊥형태 축 분리를 양방향으로 기계 강제).
8
+ * / Allow-list of CSS custom-property names permitted in a skin (FORM) delta (runtime guard).
9
+ * It physically enforces the rule that skins own shape only (radius/border/elevation/density/…)
10
+ * and never color — `define()`/`registerBuiltin()` reject any key outside this set. The reverse
11
+ * direction (shape tokens leaking into a theme delta) reuses this same set, so the color⊥shape
12
+ * axis separation is mechanically enforced both ways.
13
+ */
14
+ export declare const FORM_TOKENS: ReadonlySet<string>;
2
15
  /** 스킨 정의 결과. / Result of a skin definition. */
3
16
  export interface SkinDefineResult {
4
17
  /** 실제 등록된(가드레일 클램프가 반영된) 델타. / The actually registered delta (with guardrail clamps applied). */
@@ -7,23 +20,37 @@ export interface SkinDefineResult {
7
20
  readonly warnings: string[];
8
21
  }
9
22
  /**
10
- * 스킨 델타가 색 리터럴을 담고 있는지 검사하고, 위반 시 던진다(FORM-only, Rule 2).
11
- * / Assert a skin delta carries no color literal; throws on violation (FORM-only, Rule 2).
23
+ * 스킨(FORM)에는 형태만 담고 색은 담지 않는다는 규칙을 실제로 검사하는 함수. 왜 필요한가:
24
+ * 스킨과 테마(색)를 분리해 두어도, 개발자가 실수로 스킨 델타에 `#fff` 같은 색을 넣으면 그
25
+ * 분리가 눈에 안 띄게 무너진다 — 그래서 등록 시점에 색 리터럴이 섞이면 즉시 던져서 알아채게
26
+ * 한다(조용히 무시하지 않음).
27
+ * / Actually enforces the rule that a skin (FORM) carries shape only, never color. Why: even with
28
+ * skin/theme separation on paper, a developer slipping `#fff` into a skin delta would quietly
29
+ * break that separation — so this throws immediately at registration time instead of ignoring it.
12
30
  *
13
31
  * @param id - 스킨 id / Skin id
14
32
  * @param delta - 검사할 토큰 델타 / Token delta to validate
15
33
  * @throws FORM 토큰이 아니거나 색 리터럴이 있으면 Error / Throws if a non-FORM token or a color literal is present
34
+ * @example
35
+ * skinRegistry.define('my-skin', { '--og-radius-md': '#fff' }); // throws — 색 리터럴 검출 / color literal detected
16
36
  */
17
37
  export declare function assertFormOnly(id: string, delta: SkinTokenDelta): void;
18
38
  /**
19
- * 접근성 가드레일(불변식) 적용 — 정의 시점 클램프(§6.4).
20
- * / Apply accessibility guardrails (invariants) — clamp at definition time (§6.4).
21
- *
22
- * - focus-width < 2px → 2px 로 클램프(가시 포커스 비협상). / clamp to 2px (visible focus is non-negotiable).
39
+ * 접근성 가드레일(불변식)을 적용해 델타를 정의 시점에 안전값으로 클램프한다. `define()`/
40
+ * `registerBuiltin()` 내부에서 자동 호출되므로 보통 직접 부를 일은 없다(커스텀 등록 파이프라인·
41
+ * 테스트에서 직접 검증할 때만 예외적으로 사용). 스킨 저자가 접근성 최소 기준 이하로 값을
42
+ * 설정해도 조용히 그대로 등록되지 않도록 막는다.
43
+ * - focus-width < 2px → 2px 로 클램프(가시 포커스 비협상).
23
44
  * - focus-style: none → solid.
24
- *
25
45
  * 반환은 조정된 델타 + 경고 목록(silent override 아님 — 무엇을 클램프했는지 알린다).
26
- * / Returns the adjusted delta plus a warning list (not a silent override — it reports what was clamped).
46
+ * / Applies accessibility guardrails (invariants), clamping the delta to a safe value at
47
+ * definition time. Called automatically inside `define()`/`registerBuiltin()`, so you rarely
48
+ * call it directly (only in a custom registration pipeline or a test that checks it directly).
49
+ * Prevents a skin author from silently registering values below the minimum accessibility bar.
50
+ * - focus-width < 2px → clamped to 2px (visible focus is non-negotiable).
51
+ * - focus-style: none → solid.
52
+ * Returns the adjusted delta plus a warning list (not a silent override — it reports what was
53
+ * clamped).
27
54
  *
28
55
  * @param id - 스킨 id / Skin id
29
56
  * @param delta - 조정할 토큰 델타 / Token delta to adjust
@@ -31,10 +58,19 @@ export declare function assertFormOnly(id: string, delta: SkinTokenDelta): void;
31
58
  */
32
59
  export declare function applyGuardrails(id: string, delta: SkinTokenDelta): SkinDefineResult;
33
60
  /**
34
- * 프로세스 전역 스킨 등록소. defineSkin(사용자) 는 검증+가드레일+`<style>` 주입,
35
- * registerBuiltin(내장) 은 검증+가드레일만(CSS 는 skins.css 정적 번들 소유).
36
- * / Process-global skin registry. `define` (user) does validation + guardrails + `<style>` injection;
37
- * `registerBuiltin` (built-in) does validation + guardrails only (CSS is owned by the skins.css static bundle).
61
+ * 스킨(FORM 축 — 모서리·테두리·그림자·밀도 등 "생김새")을 등록하는 전역 레지스트리. 등록하면
62
+ * 내부에서 벌어지는 일: `define()` 은 색 리터럴이 없는지 검사 → 접근성 가드레일 클램프 →
63
+ * `.og-container[data-og-skin="id"] { ... }` 규칙을 담은 `<style>` 태그를 문서 head 에 주입한다.
64
+ * 그리드 쪽에서 `data-og-skin="id"` 속성만 설정하면 이 CSS 가 매치되어 적용된다. 내장 스킨은
65
+ * `registerBuiltin()` 으로 검증+가드레일만 거치고 실제 CSS 는 정적 번들 skins.css 가 이미
66
+ * 담당하므로 별도 주입이 없다.
67
+ * / A global registry for registering skins (the FORM axis — corner/border/shadow/density, i.e.
68
+ * "shape"). What happens internally when you register: `define()` checks for no color literals
69
+ * → clamps via accessibility guardrails → injects a `<style>` tag into document head containing
70
+ * a `.og-container[data-og-skin="id"] { ... }` rule. The grid side only needs to set the
71
+ * `data-og-skin="id"` attribute for this CSS to match and apply. Built-in skins go through
72
+ * `registerBuiltin()` for validation + guardrails only — their CSS is already owned by the
73
+ * static skins.css bundle, so no injection happens.
38
74
  *
39
75
  * @example
40
76
  * skinRegistry.define('my-skin', { '--og-radius-md': '10px', '--og-border-style': 'solid' });
@@ -70,19 +106,50 @@ export declare class SkinRegistry {
70
106
  /** 런타임 `<style>` 주입(테스트/SSR 등 document 없으면 no-op). 같은 태그를 누적 사용. */
71
107
  private _inject;
72
108
  }
73
- /** Sharp/Gothic — 엔터프라이즈 고밀도·각짐(§3.1). / Sharp/Gothic — enterprise high-density, squared corners (§3.1). */
109
+ /**
110
+ * Sharp/Gothic — 엔터프라이즈 고밀도 화면에 맞춘 각진(라운드 0) 형태. 데이터 밀도가 중요한
111
+ * 백오피스·트레이딩 화면에 어울린다.
112
+ * / Sharp/Gothic — squared (zero-radius) shape tuned for high-density enterprise screens; suits
113
+ * back-office/trading UIs where data density matters.
114
+ */
74
115
  export declare const SKIN_SHARP: SkinTokenDelta;
75
- /** Rounded — 소비자 SaaS 소프트(§3.2). / Rounded — consumer-SaaS soft look (§3.2). */
116
+ /**
117
+ * Rounded — 소비자 SaaS 에 어울리는 부드러운(둥근 모서리·큰 그림자) 형태.
118
+ * / Rounded — soft shape (rounded corners, larger shadows) suited to consumer-SaaS products.
119
+ */
76
120
  export declare const SKIN_ROUNDED: SkinTokenDelta;
77
- /** Stitch — 핸드크래프트(§3.3). 색(리넨/자수)은 theme 축. / Stitch — handcrafted look (§3.3); color (linen/embroidery) lives on the theme axis. */
121
+ /**
122
+ * Stitch — 손바느질/리넨 소재 느낌을 주는 형태(점선 테두리·텍스처). 리넨 색·자수 색 자체는
123
+ * 이 스킨이 아니라 theme(색) 축이 담당한다(색⊥형태 분리).
124
+ * / Stitch — a handcrafted, linen-textured shape (dashed borders, texture). The linen/embroidery
125
+ * color itself belongs to the theme (color) axis, not this skin (color⊥shape separation).
126
+ */
78
127
  export declare const SKIN_STITCH: SkinTokenDelta;
79
- /** Flat/Minimal — 플랫 2.0(§3.5). / Flat/Minimal — flat 2.0 (§3.5). */
128
+ /**
129
+ * Flat/Minimal — 그림자·입체감을 없앤 평평한(flat 2.0) 형태. 미니멀한 대시보드에 어울린다.
130
+ * / Flat/Minimal — a flat (flat 2.0) shape with shadows/depth removed; suits minimal dashboards.
131
+ */
80
132
  export declare const SKIN_FLAT: SkinTokenDelta;
81
- /** High-Contrast — 접근성 우선·레퍼런스(§3.6). / High-Contrast — accessibility-first reference skin (§3.6). */
133
+ /**
134
+ * High-Contrast — 접근성을 최우선에 둔 레퍼런스 스킨(굵은 테두리·큰 포커스 링·굵은 아이콘 획).
135
+ * 다른 스킨을 만들 때 "접근성 하한선이 뭔가"를 확인하는 기준으로도 쓸 수 있다.
136
+ * / High-Contrast — a reference skin that puts accessibility first (thick borders, a large focus
137
+ * ring, bold icon strokes). Also useful as a baseline for "what's the accessibility floor" when
138
+ * authoring other skins.
139
+ */
82
140
  export declare const SKIN_HIGH_CONTRAST: SkinTokenDelta;
83
- /** Material/Elevated — 중간 반경 + 정직한 그림자 엘리베이션. / Material/Elevated — medium radius plus honest shadow elevation. */
141
+ /**
142
+ * Material/Elevated — 중간 정도 반경 + 과장 없는 그림자 엘리베이션을 쓰는 형태.
143
+ * / Material/Elevated — a shape using medium-radius corners plus restrained (non-exaggerated)
144
+ * shadow elevation.
145
+ */
84
146
  export declare const SKIN_MATERIAL: SkinTokenDelta;
85
- /** 내장 스킨 카탈로그(확정 6종). id → 델타. / Built-in skin catalog (6 finalized skins). id → delta. */
147
+ /**
148
+ * 내장 스킨 카탈로그(확정 6종, id → 델타). `skinRegistry.list()`/설정 UI 에서 선택지를 보여줄 때
149
+ * 이 배열을 순회하면 된다.
150
+ * / Built-in skin catalog (6 finalized skins, id → delta). Iterate this array when building a
151
+ * picker UI or listing options via `skinRegistry.list()`.
152
+ */
86
153
  export declare const BUILTIN_SKINS: ReadonlyArray<readonly [string, SkinTokenDelta]>;
87
154
  /** 프로세스 전역 기본 레지스트리 — 내장 스킨을 부트스트랩 등록(주입 없음, CSS=skins.css).
88
155
  * / Process-global default registry — bootstraps the built-in skins (no injection; CSS=skins.css). */
@@ -1,34 +1,88 @@
1
+ /** 트리 노드 — 원본 행 데이터에 계층·펼침·라인 렌더 메타를 얹은 래퍼. / A tree node — wraps a row with hierarchy, expansion, and line-render metadata. */
1
2
  export interface TreeNode<T = any> {
3
+ /** 트리 노드 판별 플래그(항상 true). / Tree-node discriminant flag (always true). */
2
4
  _isTree: true;
5
+ /** 노드 id(idField 값). / Node id (value of `idField`). */
3
6
  _treeId: any;
7
+ /** 부모 노드 id(parentIdField 값). / Parent node id (value of `parentIdField`). */
4
8
  _treeParentId: any;
9
+ /** 트리 깊이(루트 0). / Tree depth (root is 0). */
5
10
  _depth: number;
11
+ /** 펼침 여부. / Whether the node is expanded. */
6
12
  _expanded: boolean;
13
+ /** 자식 보유 여부. / Whether the node has children. */
7
14
  _hasChildren: boolean;
15
+ /** 하위 전체(후손) 노드 수. / Total descendant node count. */
8
16
  _childCount: number;
17
+ /** true → └─ / false → ├─. / true → └─, false → ├─. */
9
18
  _isLastChild: boolean;
19
+ /** [d]=true → 깊이 d 조상에 형제가 더 있어 │ 라인 표시. / `[d]=true` → an ancestor at depth d has more siblings, so draw a │ line. */
10
20
  _ancestorHasMore: boolean[];
21
+ /** 원본 행 데이터. / The original row data. */
11
22
  data: T;
23
+ /** 자식 노드 배열. / Child nodes. */
12
24
  children: TreeNode<T>[];
13
25
  }
26
+ /** 트리 항목 별칭(=TreeNode). / Tree item alias (= TreeNode). */
14
27
  export type TreeItem<T> = TreeNode<T>;
28
+ /**
29
+ * 값이 트리 노드인지 판별하는 타입 가드. / Type guard: whether a value is a tree node.
30
+ *
31
+ * @typeParam T - 행 데이터 타입 / Row data type
32
+ * @param item - 검사할 값 / Value to test
33
+ * @returns 트리 노드이면 true / true if the value is a tree node
34
+ */
15
35
  export declare function isTreeNode<T>(item: any): item is TreeNode<T>;
36
+ /** 트리 빌드 옵션. / Options for building a tree. */
16
37
  export interface TreeBuildOptions {
38
+ /** 노드 id 필드명. / Field name holding the node id. */
17
39
  idField: string;
40
+ /** 부모 id 필드명. / Field name holding the parent id. */
18
41
  parentIdField: string;
42
+ /** 로드 시 전체 펼침 여부(기본 false). / Whether to expand all on load (default false). */
19
43
  expandOnLoad?: boolean;
20
44
  }
21
45
  /**
22
- * flat 데이터를 트리 구조로 변환.
23
- * parentId가 null/undefined/''인 행이 루트 노드.
46
+ * flat 데이터를 트리 구조로 변환. / Convert flat data into a tree structure.
47
+ *
48
+ * parentId가 null/undefined/'' 또는 미존재인 행이 루트 노드가 된다. 깊이·후손 수·
49
+ * 탐색기 라인 메타(_isLastChild, _ancestorHasMore)를 함께 계산한다.
50
+ * / Rows whose parentId is null/undefined/'' or missing become root nodes. Also computes depth,
51
+ * descendant counts, and explorer line metadata (_isLastChild, _ancestorHasMore).
52
+ *
53
+ * @typeParam T - 행 데이터 타입 / Row data type
54
+ * @param data - flat 행 배열 / Flat rows
55
+ * @param opts - id/parentId 필드 및 펼침 옵션 / id/parentId fields and expand option
56
+ * @param expandedKeys - 펼침 상태 노드 id 집합 / Set of expanded node ids
57
+ * @returns 루트 노드 배열 / Array of root nodes
58
+ * @example
59
+ * const roots = buildTree(rows, { idField: 'id', parentIdField: 'pid' });
60
+ * const flat = flattenTree(roots); // 화면 표시용 / for on-screen display
24
61
  */
25
62
  export declare function buildTree<T extends Record<string, any>>(data: T[], opts: TreeBuildOptions, expandedKeys?: Set<any>): TreeNode<T>[];
26
63
  /**
27
- * 트리를 화면에 표시할 flat 배열로 변환.
28
- * 접힌 노드(_expanded=false)의 자식은 제외.
64
+ * 트리를 화면에 표시할 flat 배열로 변환. / Flatten a tree into a display array.
65
+ *
66
+ * 접힌 노드(_expanded=false)의 자식은 제외. / Children of collapsed nodes (_expanded=false) are excluded.
67
+ *
68
+ * @typeParam T - 행 데이터 타입 / Row data type
69
+ * @param nodes - 루트 노드 배열 / Root nodes
70
+ * @returns 펼침 상태에 따른 표시 노드 배열 / Visible nodes according to expansion state
29
71
  */
30
72
  export declare function flattenTree<T>(nodes: TreeNode<T>[]): TreeNode<T>[];
31
- /** 특정 id 노드의 펼침 상태 토글 */
73
+ /**
74
+ * 특정 id 노드의 펼침 상태 토글. / Toggle the expansion state of a node id.
75
+ *
76
+ * @typeParam T - 행 데이터 타입 / Row data type
77
+ * @param expandedKeys - 펼침 상태 집합(제자리 변경) / Set of expanded ids (mutated in place)
78
+ * @param nodeId - 토글할 노드 id / Node id to toggle
79
+ */
32
80
  export declare function toggleTreeNode<T>(expandedKeys: Set<any>, nodeId: any): void;
33
- /** 모든 노드 id 수집 */
81
+ /**
82
+ * 모든 노드 id 수집(전체 펼침/접기 등에 사용). / Collect every node id (used for expand-all/collapse-all).
83
+ *
84
+ * @typeParam T - 행 데이터 타입 / Row data type
85
+ * @param nodes - 루트 노드 배열 / Root nodes
86
+ * @returns 후손 포함 전체 노드 id 배열 / All node ids including descendants
87
+ */
34
88
  export declare function collectAllTreeIds<T>(nodes: TreeNode<T>[]): any[];
@@ -1,13 +1,35 @@
1
+ /** 가상 스크롤 생성 옵션. / Virtual scroll construction options. */
1
2
  export interface VirtualScrollOptions {
3
+ /** 행 높이(px). / Row height in px. */
2
4
  rowHeight: number;
5
+ /** 뷰포트 위/아래로 여분 렌더할 행 수(기본 5). / Extra rows rendered above/below the viewport (default 5). */
3
6
  overscan?: number;
7
+ /** 가시 범위 변화 시 호출되는 렌더 콜백. / Render callback fired when the visible range changes. */
4
8
  onRender: (startIndex: number, endIndex: number) => void;
5
9
  }
10
+ /** 현재 가시 행 범위와 스크롤 오프셋. / Current visible row range and scroll offset. */
6
11
  export interface VirtualScrollRange {
12
+ /** 렌더 시작 행 인덱스. / First row index to render. */
7
13
  startIndex: number;
14
+ /** 렌더 종료 행 인덱스(포함). / Last row index to render (inclusive). */
8
15
  endIndex: number;
16
+ /** 시작 행의 상단 y 오프셋(px). / Top y-offset of the start row in px. */
9
17
  offsetY: number;
10
18
  }
19
+ /**
20
+ * 대용량 행을 위한 가상 스크롤 엔진(C0 가상스크롤). / Virtual scroll engine for large row counts (contract C0 virtual-scroll).
21
+ *
22
+ * 컨테이너의 scroll 이벤트를 rAF 로 코얼레싱하여 가시 범위만 렌더 콜백으로 통지한다.
23
+ * 스크롤 위치·뷰포트 높이·행 높이에서 시작/종료 인덱스를 계산해 DOM 노드 수를 상수로 유지한다.
24
+ * / Coalesces the container's scroll events via rAF and notifies only the visible range through
25
+ * the render callback. Derives start/end indices from scroll position, viewport height, and row
26
+ * height so the DOM node count stays constant.
27
+ *
28
+ * @example
29
+ * const vs = new VirtualScroll(container, { rowHeight: 32, onRender: (s, e) => renderRows(s, e) });
30
+ * vs.setViewportHeight(640);
31
+ * vs.setTotalRows(100000);
32
+ */
11
33
  export declare class VirtualScroll {
12
34
  private container;
13
35
  private rowHeight;
@@ -17,15 +39,57 @@ export declare class VirtualScroll {
17
39
  private _viewportHeight;
18
40
  private _rafId;
19
41
  private onRender;
42
+ /**
43
+ * 가상 스크롤 엔진 생성 및 컨테이너 scroll 리스너 부착. / Create the engine and attach the container scroll listener.
44
+ *
45
+ * @param container - 스크롤을 감지할 컨테이너 요소 / Container element whose scroll is tracked
46
+ * @param options - 행 높이·overscan·렌더 콜백 / Row height, overscan, and render callback
47
+ */
20
48
  constructor(container: HTMLElement, options: VirtualScrollOptions);
21
49
  private _onScroll;
22
50
  private _scheduleRender;
51
+ /**
52
+ * 현재 스크롤 상태 기준 가시 행 범위 계산. / Compute the visible row range for the current scroll state.
53
+ *
54
+ * overscan 을 반영해 시작/종료 인덱스와 시작 오프셋을 반환한다.
55
+ * / Returns start/end indices and the start offset, accounting for overscan.
56
+ *
57
+ * @returns 가시 범위 및 오프셋 / The visible range and offset
58
+ */
23
59
  getVisibleRange(): VirtualScrollRange;
60
+ /**
61
+ * 전체 행 수 설정 — spacer 높이 갱신 후 재렌더 예약. / Set total row count — updates spacer height and schedules a re-render.
62
+ *
63
+ * @param count - 전체 행 수 / Total number of rows
64
+ */
24
65
  setTotalRows(count: number): void;
66
+ /**
67
+ * 뷰포트 높이 설정 — 가시 행 개수 계산에 사용. / Set viewport height — used to compute the number of visible rows.
68
+ *
69
+ * @param height - 뷰포트 높이(px) / Viewport height in px
70
+ */
25
71
  setViewportHeight(height: number): void;
72
+ /**
73
+ * 행 높이 변경 — spacer 높이 갱신 후 재렌더 예약. / Change row height — updates spacer height and schedules a re-render.
74
+ *
75
+ * @param height - 새 행 높이(px) / New row height in px
76
+ */
26
77
  setRowHeight(height: number): void;
78
+ /**
79
+ * 지정 행이 보이도록 스크롤 위치 조정(이미 보이면 무이동). / Scroll so the given row is visible (no-op if already visible).
80
+ *
81
+ * @param rowIndex - 대상 행 인덱스 / Target row index
82
+ */
27
83
  scrollToRow(rowIndex: number): void;
84
+ /**
85
+ * 전체 콘텐츠 높이(전체 행 수 × 행 높이) 반환. / Return the total content height (total rows × row height).
86
+ *
87
+ * @returns 전체 높이(px) / Total height in px
88
+ */
28
89
  getTotalHeight(): number;
29
90
  private _updateSpacerHeight;
91
+ /**
92
+ * 리스너·rAF 정리. 그리드 파기 시 반드시 호출. / Tear down the listener and pending rAF; call on grid destroy.
93
+ */
30
94
  destroy(): void;
31
95
  }