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
@@ -1,4 +1,10 @@
1
1
  import { CellKey } from './types.js';
2
+ /**
3
+ * 수식 의존성 그래프. precedents/dependents 양방향 인덱스와 Kahn 위상정렬을 제공한다(§5.1~§5.4).
4
+ * DOM/렌더러/DataLayer 를 전혀 모르는 순수 알고리즘 계층이다.
5
+ * / Formula dependency graph. Provides bidirectional precedents/dependents indices plus a Kahn
6
+ * topological sort (§5.1–§5.4). A pure algorithm layer that knows nothing of DOM/renderer/DataLayer.
7
+ */
2
8
  export declare class FormulaGraph {
3
9
  /** cellKey(수식) → 그 수식이 참조하는 선행 셀 키 집합. */
4
10
  private readonly _precedents;
@@ -10,34 +16,105 @@ export declare class FormulaGraph {
10
16
  private readonly _byField;
11
17
  private _addEdge;
12
18
  private _removeEdgesFrom;
13
- /** key(수식 셀)의 선행 엣지를 deps 로 완전히 교체한다(§5.1 addFormula). */
19
+ /**
20
+ * key(수식 셀)의 선행 엣지를 deps 로 완전히 교체한다(§5.1 addFormula). 동적 의존성
21
+ * 재등록에도 쓰인다(매 평가마다 "이번에 실제로 읽은" deps 로 재구성).
22
+ * / Replace all precedent edges of `key` (a formula cell) with `deps` (§5.1 addFormula).
23
+ * Also used for dynamic-dependency re-registration (rebuilt each evaluation from the deps
24
+ * actually read this time).
25
+ *
26
+ * @param key - 수식 셀 키 / Formula cell key
27
+ * @param deps - 이 수식이 참조하는 선행 셀 키 집합 / Set of precedent cell keys this formula references
28
+ */
14
29
  addFormula(key: CellKey, deps: Set<CellKey>): void;
15
- /** 수식 삭제(clearCellFormula) — 엣지 + 역인덱스 정리. */
30
+ /**
31
+ * 수식을 삭제한다(clearCellFormula) — 엣지 + 역인덱스를 함께 정리한다.
32
+ * / Remove a formula (clearCellFormula) — cleans up edges and reverse indices together.
33
+ *
34
+ * @param key - 삭제할 수식 셀 키 / Formula cell key to remove
35
+ */
16
36
  removeFormula(key: CellKey): void;
37
+ /**
38
+ * 해당 키가 수식 셀로 등록돼 있는지 여부.
39
+ * / Whether the given key is registered as a formula cell.
40
+ *
41
+ * @param key - 검사할 셀 키 / Cell key to check
42
+ * @returns 수식 여부 / Whether it is a formula
43
+ */
17
44
  isFormula(key: CellKey): boolean;
45
+ /**
46
+ * 이 수식이 참조하는 선행 셀 키 목록.
47
+ * / Precedent cell keys referenced by this formula.
48
+ *
49
+ * @param key - 수식 셀 키 / Formula cell key
50
+ * @returns 선행 셀 키 배열 / Array of precedent cell keys
51
+ */
18
52
  getPrecedents(key: CellKey): CellKey[];
53
+ /**
54
+ * 이 키를 참조하는 수식 키 목록(dirty 전파 방향).
55
+ * / Formula keys that reference this key (dirty-propagation direction).
56
+ *
57
+ * @param key - 대상 셀 키 / Target cell key
58
+ * @returns 이 키에 의존하는 수식 키 배열 / Array of formula keys depending on this key
59
+ */
19
60
  getDependents(key: CellKey): CellKey[];
20
61
  /**
21
- * dirty 폐포(BFS): seeds 로부터 도달 가능한 모든 dependents(수식 노드만, dependents 맵의
62
+ * dirty 폐포(BFS): seeds 로부터 도달 가능한 모든 dependents(수식 노드만; dependents 맵의
22
63
  * value 는 항상 수식 키이므로 자동 보장). seed 자신이 수식이면 폐포에 포함한다
23
64
  * (§5.3 "수식 셀 편집 → 자신 + dependents dirty").
65
+ * / Dirty closure (BFS): all dependents reachable from `seeds` (formula nodes only — the
66
+ * dependents map's values are always formula keys). A seed that is itself a formula is
67
+ * included in the closure (§5.3 "editing a formula cell dirties itself + its dependents").
68
+ *
69
+ * @param seeds - 변경된 시작 셀 키 배열 / Starting changed cell keys
70
+ * @returns dirty 대상 수식 키 배열 / Array of dirty formula keys
24
71
  */
25
72
  getDependentsClosure(seeds: CellKey[]): CellKey[];
26
- /** Kahn 위상정렬(subset 내부 선행수 기준, §5.4). 잔여 노드 = 사이클 구성원. */
73
+ /**
74
+ * Kahn 위상정렬(subset 내부 선행수 기준, §5.4). 정렬에 편입되지 못한 잔여 노드가
75
+ * 사이클 구성원이다.
76
+ * / Kahn topological sort (indegree counted within `subset`, §5.4). Nodes that cannot be
77
+ * ordered are the cycle members.
78
+ *
79
+ * @param subset - 위상정렬 대상 수식 키 집합 / Formula keys to sort
80
+ * @returns `order`(위상순서) 와 `cycles`(사이클 구성원) / `order` (topological order) and `cycles` (cycle members)
81
+ */
27
82
  topoOrder(subset: CellKey[]): {
28
83
  order: CellKey[];
29
84
  cycles: CellKey[];
30
85
  };
31
86
  /**
32
- * 삭제 무효화 역조회(§5.1/F3-R28 P0): 특정 rowId(전체 field, field 생략 시) 또는
87
+ * 삭제 무효화 역조회(§5.1/F3-R28 P0): 특정 rowId(field 생략 시 전체 field) 또는
33
88
  * (rowId,field) 특정 셀을 deps 로 가진 수식 키들. removeRow/removeColumn 후크가
34
89
  * 이 결과를 onValuesChanged 의 seed 로 넘기면(대상 rowId/field 는 이미 grid 에서
35
90
  * 제거된 상태이므로) 평가 시 accessor.hasRow/hasField 가 false 를 반환해 자연스럽게
36
91
  * #REF 로 귀결한다(별도 특수 처리 없이 일반 재계산 경로 재사용).
92
+ * / Reverse lookup for delete invalidation (§5.1/F3-R28 P0): formula keys that depend on a
93
+ * given rowId (all fields when `field` is omitted) or a specific (rowId, field) cell.
94
+ * When removeRow/removeColumn hooks feed this as onValuesChanged seeds — the target
95
+ * rowId/field having already been removed from the grid — evaluation sees
96
+ * accessor.hasRow/hasField return false and naturally yields #REF (reusing the ordinary
97
+ * recalc path, no special-casing).
98
+ *
99
+ * @param rowId - 삭제/무효화된 행의 stable id / Stable id of the deleted/invalidated row
100
+ * @param field - (선택) 특정 field 로 한정 / (optional) narrow to a specific field
101
+ * @returns 해당 셀을 참조하는 수식 키 배열 / Array of formula keys referencing that cell
37
102
  */
38
103
  formulasReferencing(rowId: string, field?: string): CellKey[];
39
- /** 열 삭제 역조회(field 단독 기준, §5.1). */
104
+ /**
105
+ * 열 삭제 역조회(field 단독 기준, §5.1): 이 field 를 deps 로 가진 수식 키들.
106
+ * / Reverse lookup for column deletion (by field alone, §5.1): formula keys that depend on
107
+ * this field.
108
+ *
109
+ * @param field - 삭제된 컬럼 field 명 / Field name of the deleted column
110
+ * @returns 해당 field 를 참조하는 수식 키 배열 / Array of formula keys referencing that field
111
+ */
40
112
  formulasReferencingField(field: string): CellKey[];
41
- /** 등록된 모든 수식 키(recalculateAll 전체 재계산용). */
113
+ /**
114
+ * 등록된 모든 수식 키(recalculateAll 전체 재계산용).
115
+ * / Every registered formula key (for recalculateAll full recompute).
116
+ *
117
+ * @returns 전체 수식 키 배열 / Array of all formula keys
118
+ */
42
119
  allFormulaKeys(): CellKey[];
43
120
  }
@@ -2,5 +2,14 @@ import { AstNode } from './types.js';
2
2
  /**
3
3
  * 셀 수식 원문(선두 '=' 포함 가능)을 파싱해 AST(원시 참조 노드 포함, 정규화 전)를 만든다.
4
4
  * 정규화(normalizeRefs)는 별도 단계(§3.3)에서 수행한다.
5
+ * / Parse cell-formula source (a leading '=' is allowed) into an AST that still holds raw
6
+ * reference nodes (pre-normalization). Normalization (normalizeRefs) happens in a separate
7
+ * stage (§3.3).
8
+ *
9
+ * @param src - 셀 수식 원문(예: "=SUM(A1:A5)") / Cell-formula source (e.g. "=SUM(A1:A5)")
10
+ * @returns 원시 참조 노드를 포함한 정규화 전 AST / Pre-normalization AST including raw reference nodes
11
+ * @throws SyntaxError 문법 오류(닫는 괄호 누락, 예상치 못한 토큰 등) / on grammar errors (missing paren, unexpected token, …)
12
+ * @example
13
+ * const ast = parseFormula('=[price] * 1.1');
5
14
  */
6
15
  export declare function parseFormula(src: string): AstNode;
@@ -1,17 +1,79 @@
1
1
  import { CellKey, FormulaCell } from './types.js';
2
+ /**
3
+ * 셀 수식 사이드카 저장소. 값과 분리해 (rowId, field) 키로 수식 셀을 보관한다(§4.1).
4
+ * stable-id 앵커(§3.2/C0.5)라 정렬/필터에 흔들리지 않는다.
5
+ * / Sidecar store for cell formulas. Keeps formula cells keyed by (rowId, field), separate
6
+ * from values (§4.1). The stable-id anchor (§3.2/C0.5) keeps keys stable across sort/filter.
7
+ */
2
8
  export declare class FormulaStore {
3
9
  private readonly _cells;
10
+ /**
11
+ * (rowId, field) 셀에 수식을 저장한다(기존이 있으면 덮어쓴다).
12
+ * / Store a formula for the (rowId, field) cell (overwrites any existing entry).
13
+ *
14
+ * @param rowId - 대상 행의 stable id / Stable id of the target row
15
+ * @param field - 컬럼 field 명 / Column field name
16
+ * @param cell - 저장할 수식 셀 / Formula cell to store
17
+ */
4
18
  setFormula(rowId: string, field: string, cell: FormulaCell): void;
19
+ /**
20
+ * (rowId, field) 셀의 수식을 조회한다.
21
+ * / Look up the formula for the (rowId, field) cell.
22
+ *
23
+ * @param rowId - 대상 행의 stable id / Stable id of the target row
24
+ * @param field - 컬럼 field 명 / Column field name
25
+ * @returns 수식 셀 또는 없으면 undefined / The formula cell, or undefined if absent
26
+ */
5
27
  getFormula(rowId: string, field: string): FormulaCell | undefined;
28
+ /**
29
+ * (rowId, field) 셀의 수식을 제거한다.
30
+ * / Remove the formula for the (rowId, field) cell.
31
+ *
32
+ * @param rowId - 대상 행의 stable id / Stable id of the target row
33
+ * @param field - 컬럼 field 명 / Column field name
34
+ */
6
35
  clearFormula(rowId: string, field: string): void;
36
+ /**
37
+ * (rowId, field) 셀에 수식이 있는지 여부.
38
+ * / Whether the (rowId, field) cell has a formula.
39
+ *
40
+ * @param rowId - 대상 행의 stable id / Stable id of the target row
41
+ * @param field - 컬럼 field 명 / Column field name
42
+ * @returns 수식 존재 여부 / Whether a formula exists
43
+ */
7
44
  hasFormula(rowId: string, field: string): boolean;
45
+ /**
46
+ * CellKey 로 직접 수식을 조회한다(내부 키를 이미 알고 있을 때).
47
+ * / Look up a formula directly by CellKey (when the internal key is already known).
48
+ *
49
+ * @param key - 셀 키(rowId+field 합성) / Cell key (composite of rowId+field)
50
+ * @returns 수식 셀 또는 없으면 undefined / The formula cell, or undefined if absent
51
+ */
8
52
  getFormulaByKey(key: CellKey): FormulaCell | undefined;
53
+ /**
54
+ * 저장된 모든 수식 셀을 (rowId, field, cell) 형태로 나열한다.
55
+ * / List every stored formula cell as { rowId, field, cell }.
56
+ *
57
+ * @returns 전체 수식 셀 배열 / Array of all formula cells
58
+ */
9
59
  getAllFormulaCells(): Array<{
10
60
  rowId: string;
11
61
  field: string;
12
62
  cell: FormulaCell;
13
63
  }>;
14
- /** applySort/applyFilter 후크가 dirty 대상으로 모아야 할 range-보유 수식 키(§3.5 P0). */
64
+ /**
65
+ * applySort/applyFilter 후크가 dirty 대상으로 모아야 할 range-보유 수식 키들(§3.5 P0).
66
+ * / Keys of formulas that hold a range reference — the set applySort/applyFilter hooks must
67
+ * mark dirty (§3.5 P0).
68
+ *
69
+ * @returns 범위 참조를 가진 수식 셀 키 배열 / Array of formula cell keys bearing a range reference
70
+ */
15
71
  getRangeBearingKeys(): CellKey[];
72
+ /**
73
+ * 저장된 수식 셀 개수.
74
+ * / Number of stored formula cells.
75
+ *
76
+ * @returns 수식 셀 개수 / Count of formula cells
77
+ */
16
78
  size(): number;
17
79
  }
@@ -0,0 +1,138 @@
1
+ import { OGDecimal } from '../OGDecimal.js';
2
+ import { CellValue, FormulaErrorCode } from './types.js';
3
+ /** 인자 1개의 지연 평가 결과(에러 격리형). / Lazy result of one argument (error-isolated). */
4
+ export type FnArgResult = {
5
+ readonly ok: true;
6
+ readonly value: CellValue;
7
+ } | {
8
+ readonly ok: false;
9
+ readonly error: FormulaErrorCode;
10
+ };
11
+ /**
12
+ * 함수 인자 1개 — 스칼라/리스트/에러격리 평가를 제공한다(§2.3 EvalArg).
13
+ * / A single function argument — scalar/list/error-isolated evaluation (§2.3 EvalArg).
14
+ */
15
+ export interface FnArg {
16
+ /** 스칼라로 평가(에러면 FormulaEvalError throw — evaluate() 경계가 격리). / Evaluate as scalar (throws on error; evaluate() boundary isolates it). */
17
+ scalar(): CellValue;
18
+ /** 스칼라로 평가하되 에러를 값으로 포획(IFERROR 류). / Evaluate as scalar but capture errors as a value (IFERROR-like). */
19
+ tryScalar(): FnArgResult;
20
+ /** 리스트로 평가(범위→멤버 나열, 스칼라→단일 원소). / Evaluate as list (range→members, scalar→one element). */
21
+ list(): CellValue[];
22
+ }
23
+ /**
24
+ * 함수 평가 컨텍스트 — 변환/근사표식/실패/집계 도우미(§2.3 EvalCtx).
25
+ * / Function evaluation context — conversions, approx flag, failure, aggregation helper (§2.3 EvalCtx).
26
+ */
27
+ export interface FnEvalCtx {
28
+ /** 나눗셈 정밀도(§8.1 divisionPrecision). / Division precision (§8.1). */
29
+ readonly prec: number;
30
+ /** 결정론 주입 시각(volatile 함수용, 불변식 1). / Injected deterministic clock (for volatile funcs, invariant 1). */
31
+ readonly now: () => number;
32
+ /** 인자 개수. / Argument count. */
33
+ readonly argCount: number;
34
+ /** float 근사가 섞였음을 표식(SQRT 등). / Mark that a float approximation was involved (SQRT, …). */
35
+ markApprox(): void;
36
+ /** 표준 오류로 실패(무예외 불변식 — 내부 FormulaEvalError 로 격리). / Fail with a standard error (never-throw invariant). */
37
+ fail(code: FormulaErrorCode): never;
38
+ /** 산술 문맥 수치 변환(빈 셀만 관대·비수치는 #VALUE). / Numeric coercion (empty tolerant; non-numeric → #VALUE). */
39
+ toNum(v: CellValue): OGDecimal;
40
+ /** 불리언 문맥 변환. / Boolean coercion. */
41
+ toBool(v: CellValue): boolean;
42
+ /** 표시 문자열 변환. / Display-string coercion. */
43
+ toStr(v: CellValue): string;
44
+ /** 수치로 해석 가능한 값인가. / Whether the value is interpretable as numeric. */
45
+ isNumeric(v: CellValue): boolean;
46
+ /** 전 인자를 평탄화(범위 전개)하고 에러 토큰 멤버는 제외(집계 오염 차단, C11). / Flatten all args (expand ranges) excluding error-token members (aggregation guard, C11). */
47
+ collect(): CellValue[];
48
+ }
49
+ /** 함수 인자 1개의 시그니처 메타(자동완성·인자힌트 데이터원). / Signature meta for one parameter (autocomplete/arg-hint source). */
50
+ export interface FunctionParam {
51
+ /** 인자 표시명. / Parameter display name. */
52
+ readonly name: string;
53
+ /** 선택 인자 여부. / Whether the parameter is optional. */
54
+ readonly optional?: boolean;
55
+ /** 가변 인자 여부. / Whether the parameter is variadic. */
56
+ readonly variadic?: boolean;
57
+ }
58
+ /** 함수 시그니처(에디터 6기능 데이터원, REQ-T8-827). 렌더/위젯은 DD-09/DD-03. / Function signature (editor data source; widgets belong to DD-09/DD-03). */
59
+ export interface FunctionSignature {
60
+ /** 인자 목록. / Parameter list. */
61
+ readonly params: readonly FunctionParam[];
62
+ /** 한 줄 요약. / One-line summary. */
63
+ readonly summary?: string;
64
+ /** 반환 설명. / Return description. */
65
+ readonly returns?: string;
66
+ }
67
+ /**
68
+ * 함수 1개의 순수 정의(§2.3 FunctionDef 정본). 값 목록/스칼라 인자를 받아 CellValue 를 산출.
69
+ * 무예외 계약: throw 대신 `ctx.fail(code)` 로 오류 격리(오버라이드 함수도 동일, CRC 불변식 ③).
70
+ * / Pure definition of one function (§2.3 canonical FunctionDef). Never-throw contract:
71
+ * isolate errors via `ctx.fail(code)` rather than throwing (overrides included).
72
+ */
73
+ export interface FunctionDef {
74
+ /** 정규화 대문자 이름. / Normalized upper-case name. */
75
+ readonly name: string;
76
+ /** 인자 개수 제약. / Arity constraint. */
77
+ readonly arity: {
78
+ readonly min: number;
79
+ readonly max: number | 'variadic';
80
+ };
81
+ /** 번들 배분·Go/NoGo 집계 기준(REQ-T8-844). / Bundle-budget/Go-NoGo tier (REQ-T8-844). */
82
+ readonly tier: 'essential' | 'extended';
83
+ /** 순수 평가. / Pure evaluation. */
84
+ evaluate(args: FnArg[], ctx: FnEvalCtx): CellValue;
85
+ /** (선택) 에디터 SPI 메타(REQ-T8-827). / (optional) editor SPI meta (REQ-T8-827). */
86
+ readonly signature?: FunctionSignature;
87
+ /** (선택) spill 산출(동적배열, REQ-T8-112). / (optional) spill output (dynamic arrays, REQ-T8-112). */
88
+ readonly spills?: boolean;
89
+ /**
90
+ * (선택·additive) 휘발성(§R.4, DD-10 흡수). 'volatile'(NOW/RAND: 매 재계산 재평가·캐시 무효)
91
+ * | 'stable'(기본). `CalcCacheStore` 는 volatile 참조 셀을 캐시에서 제외한다.
92
+ * / (optional) volatility (§R.4). 'volatile' funcs are excluded from CalcCacheStore.
93
+ */
94
+ readonly volatility?: 'stable' | 'volatile';
95
+ /** (선택·additive) 지역화 표시명(§R.4). 평가는 정규화 name 기준, 라벨만 i18n. / (optional) localized display name (§R.4). */
96
+ readonly i18nName?: Readonly<Record<string, string>>;
97
+ }
98
+ /**
99
+ * 함수 등록·조회·**오버라이드** SPI(§2.3). DD-10 `IRegistry<FunctionDef>` 동형(C1) — register/get/has
100
+ * 는 IRegistry 코어, list(tier)·child 는 본 레지스트리 확장.
101
+ * / Function register/get/override SPI (§2.3). Isomorphic to DD-10 IRegistry<FunctionDef> (C1).
102
+ */
103
+ export interface FunctionRegistry {
104
+ /**
105
+ * 등록·교체. 기본은 **우발적 섀도잉 방지**(§R.5): 기존 이름 재등록은 `override` 미지정 시 throw.
106
+ * / Register/replace. Fail-fast on accidental shadowing (§R.5): re-registering an existing name
107
+ * without `override` throws.
108
+ */
109
+ register(def: FunctionDef, opts?: {
110
+ override?: boolean;
111
+ }): void;
112
+ /** 미등록 → undefined(평가 시 #NAME). / Unregistered → undefined (#NAME at eval). */
113
+ get(name: string): FunctionDef | undefined;
114
+ /** 등록 여부(부모 스코프 포함). / Whether registered (parent scope included). */
115
+ has(name: string): boolean;
116
+ /** tier 별 목록(번들 예산 집계·Go/NoGo, REQ-T8-844). / List by tier (bundle budget/Go-NoGo). */
117
+ list(tier?: 'essential' | 'extended'): FunctionDef[];
118
+ /** 자식 스코프 — per-instance 오버라이드(전역 오염 없음, 부모 폴백). / Child scope — per-instance override (no global pollution, parent fallback). */
119
+ child(): FunctionRegistry;
120
+ }
121
+ /** 함수 이름 정규화(대문자·trim) — register/get 진입 공통. / Normalize a function name (upper-case, trim). */
122
+ export declare function normalizeFnName(name: string): string;
123
+ /**
124
+ * `FunctionRegistry` 기본 구현. 얇은 Map + 부모 폴백 체인(§2.3 child). 직렬화 없음(코드 참조).
125
+ * / Default `FunctionRegistry` implementation. Thin Map + parent-fallback chain (§2.3 child).
126
+ */
127
+ export declare class TieredFunctionRegistry implements FunctionRegistry {
128
+ private readonly _map;
129
+ private readonly _parent;
130
+ constructor(parent?: TieredFunctionRegistry);
131
+ register(def: FunctionDef, opts?: {
132
+ override?: boolean;
133
+ }): void;
134
+ get(name: string): FunctionDef | undefined;
135
+ has(name: string): boolean;
136
+ list(tier?: 'essential' | 'extended'): FunctionDef[];
137
+ child(): FunctionRegistry;
138
+ }
@@ -0,0 +1,86 @@
1
+ import { AstNode, CellKey, FormulaGridAccessor } from './types.js';
2
+ import { EvalOutcome, EvalOptions } from './FormulaEvaluator.js';
3
+ /** 단조 증가 세대(브랜드 타입). 값 변경/구조편집/대량 무효화 시 증가(§2.4). / Monotonic generation (branded). */
4
+ export type Generation = number & {
5
+ readonly __brand: 'Generation';
6
+ };
7
+ /** 원시 수를 Generation 으로 태그(내부 전용). / Tag a raw number as a Generation (internal). */
8
+ export declare function makeGeneration(n: number): Generation;
9
+ /** 비동기 계산 결과의 세대 봉투(§2.4) — executor 가 반환, 코디네이터가 게이트. / Generational envelope of an async result. */
10
+ export interface GenerationalResult<T> {
11
+ /** 요청 발행 시점 세대. / Generation at request-issue time. */
12
+ readonly gen: Generation;
13
+ /** 결과 값. / Result value. */
14
+ readonly value: T;
15
+ }
16
+ /**
17
+ * 단조 세대 카운터. 스테일 게이트의 단일 진실(§2.4/§3.5). in-flight 폐기의 근거.
18
+ * / Monotonic generation counter — single source of truth for the stale gate (§2.4/§3.5).
19
+ *
20
+ * @example
21
+ * const gc = new GenerationCounter();
22
+ * const g = gc.current();
23
+ * gc.invalidate(); // 대량 변경 → 세대 증가
24
+ * gc.isCurrent(g); // false → 늦게 온 g 세대 결과는 폐기
25
+ */
26
+ export declare class GenerationCounter {
27
+ private _g;
28
+ /** 현재 세대. / Current generation. */
29
+ current(): Generation;
30
+ /** 세대를 1 올리고 새 값을 반환(in-flight 폐기). / Bump the generation by 1 and return it (discards in-flight). */
31
+ invalidate(): Generation;
32
+ /** 주어진 세대가 현재와 일치하는가(스테일 게이트). / Whether the given generation equals the current (stale gate). */
33
+ isCurrent(gen: Generation): boolean;
34
+ }
35
+ /**
36
+ * 세대 게이트 적용 도우미(§3.5 스텝4): 결과 세대가 현재와 일치할 때만 apply 를 호출한다.
37
+ * 불일치면 폐기(apply 미호출)하고 false 반환. "A 요청 후 즉시 B → 늦은 A 무시" 계약을 캡슐.
38
+ * / Apply a generational result only if its generation is still current (§3.5 step 4); otherwise
39
+ * discard (apply not called) and return false.
40
+ *
41
+ * @param counter - 세대 카운터 / Generation counter
42
+ * @param result - 세대 봉투 결과 / Generational envelope result
43
+ * @param apply - 세대 일치 시 실행할 적용 함수 / Applied only when generations match
44
+ * @returns 적용되었으면 true, 폐기되었으면 false / true if applied, false if discarded
45
+ */
46
+ export declare function applyIfCurrent<T>(counter: GenerationCounter, result: GenerationalResult<T>, apply: (value: T) => void): boolean;
47
+ /** 비동기 계산 배치 요청(§2.4). / An async calc batch request (§2.4). */
48
+ export interface AsyncCalcRequest {
49
+ /** 평가 대상 (ast, host) 목록. / (ast, host) pairs to evaluate. */
50
+ readonly items: ReadonlyArray<{
51
+ ast: AstNode;
52
+ host: {
53
+ rowId: string;
54
+ field: string;
55
+ };
56
+ }>;
57
+ }
58
+ /**
59
+ * 계산 실행기 seam(§2.4, Strategy) — 동기(기본)/워커/목 교체 가능. 워커 미지원 시 evalSync 폴백.
60
+ * / Calc executor seam (§2.4, Strategy) — sync (default) / worker / mock. Falls back to evalSync
61
+ * when workers are unsupported (REQ-T8-843).
62
+ */
63
+ export interface CalcExecutor {
64
+ /** 동기 평가(메인스레드). 항상 존재(폴백). / Synchronous evaluation (main thread). Always present (fallback). */
65
+ evalSync(ast: AstNode, host: {
66
+ rowId: string;
67
+ field: string;
68
+ }, accessor: FormulaGridAccessor, opts?: EvalOptions): EvalOutcome;
69
+ /** (선택) 비동기 오프로드(REQ-T8-843) — 순수·직렬화가능 계약. 세대 봉투로 반환. / (optional) async offload — returns a generational envelope. */
70
+ evalAsync?(batch: AsyncCalcRequest, accessor: FormulaGridAccessor, gen: Generation, opts?: EvalOptions): Promise<GenerationalResult<EvalOutcome[]>>;
71
+ /** 워커 지원 여부(false → evalSync 폴백, REQ-T8-843). / Whether workers are supported (false → evalSync fallback). */
72
+ readonly supportsWorker: boolean;
73
+ }
74
+ /**
75
+ * 기본 동기 실행기 — `evaluate` 를 그대로 위임한다(폴백 계약). 워커 미지원.
76
+ * / Default synchronous executor — delegates straight to `evaluate` (fallback contract). No worker.
77
+ */
78
+ export declare class SyncCalcExecutor implements CalcExecutor {
79
+ readonly supportsWorker = false;
80
+ evalSync(ast: AstNode, host: {
81
+ rowId: string;
82
+ field: string;
83
+ }, accessor: FormulaGridAccessor, opts?: EvalOptions): EvalOutcome;
84
+ }
85
+ /** 편의 재수출(테스트/소비자). / Convenience re-export. */
86
+ export type { CellKey };