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,35 +1,70 @@
1
1
  /**
2
- * 셀 병합 관리 엔진.
2
+ * 셀 병합 관리 엔진. / Cell-merge management engine.
3
3
  *
4
- * 두 가지 병합 방식 지원:
5
- * 1. 동적 병합: mergeCells([{row, col, rowSpan, colSpan}])
6
- * 2. 자동 병합: 같은 필드에 같은 값이 연속되면 자동으로 rowSpan
4
+ * 두 가지 병합 방식 지원 / Supports two merge modes:
5
+ * 1. 동적 병합 / Explicit merge: applyMergeCells([{row, col, rowSpan, colSpan}])
6
+ * 2. 자동 병합 / Auto merge: 같은 필드에 같은 값이 연속되면 자동으로 rowSpan
7
+ * / consecutive equal values in a field collapse into a rowSpan automatically
7
8
  */
9
+ /** 병합 대상 셀 정의(기준 셀). / A cell to merge (the anchor cell). */
8
10
  export interface MergeCell {
11
+ /** 표시 행 인덱스(0-base). / Display row index (0-based). */
9
12
  row: number;
13
+ /** 리프 컬럼 인덱스(0-base). / Leaf column index (0-based). */
10
14
  col: number;
15
+ /** 세로 병합 칸 수(1 이상, 기본 1). / Vertical span count (>=1, default 1). */
11
16
  rowSpan?: number;
17
+ /** 가로 병합 칸 수(1 이상, 기본 1). / Horizontal span count (>=1, default 1). */
12
18
  colSpan?: number;
13
19
  }
20
+ /** 특정 (row,col) 셀의 병합 결과 정보. / Resolved merge info for a specific (row,col) cell. */
14
21
  export interface MergeInfo {
22
+ /** 세로 병합 칸 수. / Vertical span count. */
15
23
  rowSpan: number;
24
+ /** 가로 병합 칸 수. / Horizontal span count. */
16
25
  colSpan: number;
26
+ /** 병합으로 숨겨진 셀(렌더링 생략). / Cell hidden by a merge (skipped in rendering). */
17
27
  hidden: boolean;
18
28
  }
29
+ /**
30
+ * 병합 맵 계산·조회를 담당하는 엔진. / Engine that computes and serves the merge map.
31
+ *
32
+ * @example
33
+ * const merge = new MergeEngine();
34
+ * merge.applyMergeCells([{ row: 0, col: 1, rowSpan: 2 }]);
35
+ * merge.getInfo(0, 1); // { rowSpan: 2, colSpan: 1, hidden: false }
36
+ */
19
37
  export declare class MergeEngine {
20
38
  private _map;
21
39
  private static _key;
22
- /** 수동 병합 정의 목록으로 맵 구성 */
40
+ /**
41
+ * 수동 병합 정의 목록으로 맵 구성. / Build the merge map from an explicit list of merge cells.
42
+ *
43
+ * 각 기준 셀은 span 을 갖고, 병합에 삼켜진 하위 셀은 `hidden:true` 로 표시된다.
44
+ * / Each anchor cell keeps its span; cells swallowed by the merge are marked `hidden:true`.
45
+ *
46
+ * @param cells - 병합할 셀 정의 목록 / List of cells to merge
47
+ */
23
48
  applyMergeCells(cells: MergeCell[]): void;
24
49
  /**
25
- * 자동 병합: 지정 컬럼 인덱스 목록에 대해 연속 같은 값을 rowSpan으로 병합.
26
- * data: 현재 표시 순서의 행 배열, colIndexes: 자동병합할 leaf 컬럼 인덱스
27
- * fields: colIndexes[i] 에 대응하는 field 이름
50
+ * 자동 병합: 지정 컬럼에서 연속 같은 값을 rowSpan 으로 병합.
51
+ * / Auto merge: collapse consecutive equal values in the given columns into rowSpans.
52
+ *
53
+ * @param data - 현재 표시 순서의 행 배열 / Rows in current display order
54
+ * @param colIndexes - 자동 병합할 leaf 컬럼 인덱스 목록 / Leaf column indexes to auto-merge
55
+ * @param fields - colIndexes[i] 에 대응하는 field 이름 / Field names matching each `colIndexes[i]`
28
56
  */
29
57
  applyAutoMerge(data: Record<string, any>[], colIndexes: number[], fields: string[]): void;
30
- /** 셀 병합 정보 조회. 없으면 null */
58
+ /**
59
+ * 셀 병합 정보 조회. / Look up merge info for a cell.
60
+ *
61
+ * @param row - 표시 행 인덱스 / Display row index
62
+ * @param col - 리프 컬럼 인덱스 / Leaf column index
63
+ * @returns 병합 정보, 없으면 null / Merge info, or null if the cell is not merged
64
+ */
31
65
  getInfo(row: number, col: number): MergeInfo | null;
32
- /** 병합 맵 초기화 */
66
+ /** 병합 맵 초기화. / Clear the merge map. */
33
67
  clear(): void;
68
+ /** 병합 맵이 비었는지 여부. / Whether the merge map is empty. */
34
69
  get isEmpty(): boolean;
35
70
  }
@@ -1,49 +1,180 @@
1
+ /** OGDecimal 로 변환 가능한 입력 타입. / Input types convertible to an OGDecimal. */
1
2
  export type OGDecimalLike = string | number | bigint | OGDecimal;
3
+ /**
4
+ * BigInt 기반 임의정밀도 소수. / BigInt-based arbitrary-precision decimal.
5
+ *
6
+ * 값은 `coefficient / 10^scale` 로 표현되며, IEEE 754 오차 없이 정확한 사칙연산·집계를 제공한다.
7
+ * 음원 수익 배분처럼 수백 자리 정밀도가 필요한 계산을 외부 라이브러리 없이(ES2020+ BigInt) 지원한다.
8
+ * 인스턴스는 불변(immutable)이며, 모든 연산은 새 인스턴스를 반환한다.
9
+ * / A value is represented as `coefficient / 10^scale`, giving exact arithmetic and aggregation with
10
+ * no IEEE 754 error. Supports hundreds-of-digits precision (e.g. royalty splits) with no external
11
+ * library (ES2020+ BigInt). Instances are immutable; every operation returns a new instance.
12
+ *
13
+ * @example
14
+ * const total = OGDecimal.from('0.1').add('0.2'); // 정확히 0.3 / exactly 0.3
15
+ * total.toFixed(2); // '0.30'
16
+ */
2
17
  export declare class OGDecimal {
3
18
  private readonly _c;
4
19
  private readonly _s;
20
+ /**
21
+ * coefficient/scale 로 직접 생성(보통 {@link OGDecimal.from} 사용 권장).
22
+ * / Construct directly from coefficient/scale (prefer {@link OGDecimal.from} in most cases).
23
+ *
24
+ * @param coefficient - 부호 포함 정수 계수 / Signed integer coefficient
25
+ * @param scale - 소수점 아래 자릿수(음수는 0으로 클램프) / Number of fractional digits (negatives clamp to 0)
26
+ */
5
27
  constructor(coefficient: bigint, scale: number);
28
+ /**
29
+ * 문자열·숫자·bigint·OGDecimal 을 OGDecimal 로 변환. / Convert a string/number/bigint/OGDecimal into an OGDecimal.
30
+ *
31
+ * 빈 값/'null'/'undefined'/'NaN' 은 0 으로 처리한다. / Empty/'null'/'undefined'/'NaN' inputs map to 0.
32
+ * ⚠️ number 입력은 이미 부동소수 오차를 담을 수 있으니 정밀 계산은 문자열 입력 권장.
33
+ * / ⚠️ A number input may already carry float error; prefer string input for exact math.
34
+ *
35
+ * @param value - 변환할 값 / Value to convert
36
+ * @returns 대응하는 OGDecimal / The corresponding OGDecimal
37
+ */
6
38
  static from(value: OGDecimalLike): OGDecimal;
39
+ /** 0 값 생성. / Create a zero value. */
7
40
  static zero(): OGDecimal;
41
+ /** 1 값 생성. / Create a one value. */
8
42
  static one(): OGDecimal;
9
43
  private static _align;
44
+ /**
45
+ * 덧셈(정확). / Exact addition.
46
+ *
47
+ * @param other - 더할 값 / Value to add
48
+ * @returns 합을 담은 새 OGDecimal / A new OGDecimal holding the sum
49
+ */
10
50
  add(other: OGDecimalLike): OGDecimal;
51
+ /**
52
+ * 뺄셈(정확). / Exact subtraction.
53
+ *
54
+ * @param other - 뺄 값 / Value to subtract
55
+ * @returns 차를 담은 새 OGDecimal / A new OGDecimal holding the difference
56
+ */
11
57
  sub(other: OGDecimalLike): OGDecimal;
58
+ /**
59
+ * 곱셈(정확). / Exact multiplication.
60
+ *
61
+ * @param other - 곱할 값 / Value to multiply by
62
+ * @returns 곱을 담은 새 OGDecimal / A new OGDecimal holding the product
63
+ */
12
64
  mul(other: OGDecimalLike): OGDecimal;
13
65
  /**
14
- * 나눗셈. precision = 결과 소수점 자리수 (기본 20).
15
- * 수익 배분처럼 소수 수백 자리가 필요하면 precision을 높인다.
66
+ * 나눗셈. / Division.
67
+ *
68
+ * precision = 결과 소수점 자리수(기본 20). 수익 배분처럼 소수 수백 자리가 필요하면 precision 을 높인다.
69
+ * / `precision` is the number of result decimal places (default 20). Raise it when hundreds of
70
+ * fractional digits are required (e.g. royalty splits).
71
+ *
72
+ * @param other - 제수(0 금지) / Divisor (must be non-zero)
73
+ * @param precision - 결과 소수점 자리수(기본 20) / Result decimal places (default 20)
74
+ * @returns 몫을 담은 새 OGDecimal / A new OGDecimal holding the quotient
75
+ * @throws 제수가 0 이면 Error / Error when the divisor is 0
16
76
  */
17
77
  div(other: OGDecimalLike, precision?: number): OGDecimal;
18
- /** 나머지 (정수 나머지와 동일한 개념을 소수에 적용) */
78
+ /**
79
+ * 나머지(정수 나머지 개념을 소수에 적용). / Remainder (integer-remainder concept applied to decimals).
80
+ *
81
+ * @param other - 제수 / Divisor
82
+ * @returns 나머지를 담은 새 OGDecimal / A new OGDecimal holding the remainder
83
+ */
19
84
  mod(other: OGDecimalLike): OGDecimal;
20
- /** 부호 반전 */
85
+ /**
86
+ * 부호 반전. / Negation.
87
+ *
88
+ * @returns 부호를 뒤집은 새 OGDecimal / A new OGDecimal with the sign flipped
89
+ */
21
90
  neg(): OGDecimal;
22
- /** 절댓값 */
91
+ /**
92
+ * 절댓값. / Absolute value.
93
+ *
94
+ * @returns 절댓값을 담은 새 OGDecimal / A new OGDecimal holding the absolute value
95
+ */
23
96
  abs(): OGDecimal;
97
+ /**
98
+ * 같음 비교. / Equality comparison.
99
+ * @param other - 비교 대상 / Value to compare
100
+ * @returns 값이 같으면 true / true if equal
101
+ */
24
102
  eq(other: OGDecimalLike): boolean;
103
+ /**
104
+ * 초과 비교. / Greater-than comparison.
105
+ * @param other - 비교 대상 / Value to compare
106
+ * @returns this > other 이면 true / true if this > other
107
+ */
25
108
  gt(other: OGDecimalLike): boolean;
109
+ /**
110
+ * 미만 비교. / Less-than comparison.
111
+ * @param other - 비교 대상 / Value to compare
112
+ * @returns this < other 이면 true / true if this < other
113
+ */
26
114
  lt(other: OGDecimalLike): boolean;
115
+ /** 이상(>=) 비교. / Greater-than-or-equal comparison. @param other 비교 대상 / Value to compare @returns this >= other 이면 true / true if this >= other */
27
116
  gte(other: OGDecimalLike): boolean;
117
+ /** 이하(<=) 비교. / Less-than-or-equal comparison. @param other 비교 대상 / Value to compare @returns this <= other 이면 true / true if this <= other */
28
118
  lte(other: OGDecimalLike): boolean;
119
+ /** 0 인지 여부. / Whether the value is zero. @returns 0 이면 true / true if zero */
29
120
  isZero(): boolean;
121
+ /** 음수인지 여부. / Whether the value is negative. @returns 음수이면 true / true if negative */
30
122
  isNeg(): boolean;
123
+ /** 양수인지 여부. / Whether the value is positive. @returns 양수이면 true / true if positive */
31
124
  isPos(): boolean;
32
125
  /**
33
- * 지정 소수점 자리수로 반올림(Half-up) 후 문자열 반환.
34
- * 음원 배분 등 정확한 자리수 표시에 사용.
126
+ * 지정 소수점 자리수로 반올림(Half-up) 후 문자열 반환. / Round Half-up to `dp` places and return a string.
127
+ *
128
+ * 음원 배분 등 정확한 자리수 표시에 사용. / Used for exact fixed-place display (e.g. royalty splits).
129
+ *
130
+ * @param dp - 소수점 자리수 / Number of decimal places
131
+ * @returns 반올림된 고정소수 문자열 / The rounded fixed-point string
35
132
  */
36
133
  toFixed(dp: number): string;
37
- /** 정규화(후행 0 제거) 후 최소 표현 문자열 반환 */
134
+ /**
135
+ * 정규화(후행 0 제거) 후 최소 표현 문자열 반환. / Return the minimal string after normalization (trailing zeros removed).
136
+ *
137
+ * @returns 최소 표현 문자열 / The minimal string representation
138
+ */
38
139
  toString(): string;
39
- /** number로 변환 (정밀도 손실 주의 — 표시 전용) */
140
+ /**
141
+ * number 로 변환. / Convert to a number.
142
+ *
143
+ * ⚠️ 정밀도 손실 주의 — 표시/차트 등 근사 용도 전용, 정확 계산엔 쓰지 말 것.
144
+ * / ⚠️ Lossy — for display/chart approximations only; do not use for exact math.
145
+ *
146
+ * @returns 근사 number 값 / The approximate number value
147
+ */
40
148
  toNumber(): number;
41
- /** 정확한 합산 (내부적으로 BigInt 정수 연산) */
149
+ /**
150
+ * 정확한 합산(내부적으로 BigInt 정수 연산). / Exact summation (BigInt integer arithmetic internally).
151
+ *
152
+ * @param arr - 합산할 값 배열 / Values to sum
153
+ * @returns 합계 OGDecimal(빈 배열 → 0) / The sum (empty array → 0)
154
+ */
42
155
  static sum(arr: OGDecimalLike[]): OGDecimal;
43
- /** 정확한 평균. precision = 나눗셈 소수점 자리수 */
156
+ /**
157
+ * 정확한 평균. / Exact average.
158
+ *
159
+ * @param arr - 평균 낼 값 배열 / Values to average
160
+ * @param precision - 나눗셈 소수점 자리수(기본 20) / Division decimal places (default 20)
161
+ * @returns 평균 OGDecimal(빈 배열 → 0) / The average (empty array → 0)
162
+ */
44
163
  static avg(arr: OGDecimalLike[], precision?: number): OGDecimal;
45
- /** 배열 최솟값 */
164
+ /**
165
+ * 배열 최솟값. / Minimum of an array.
166
+ *
167
+ * @param arr - 값 배열(비어 있으면 예외) / Values (throws if empty)
168
+ * @returns 최솟값 OGDecimal / The minimum value
169
+ * @throws 빈 배열이면 Error / Error when the array is empty
170
+ */
46
171
  static min(arr: OGDecimalLike[]): OGDecimal;
47
- /** 배열 최댓값 */
172
+ /**
173
+ * 배열 최댓값. / Maximum of an array.
174
+ *
175
+ * @param arr - 값 배열(비어 있으면 예외) / Values (throws if empty)
176
+ * @returns 최댓값 OGDecimal / The maximum value
177
+ * @throws 빈 배열이면 Error / Error when the array is empty
178
+ */
48
179
  static max(arr: OGDecimalLike[]): OGDecimal;
49
180
  }