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
@@ -0,0 +1,47 @@
1
+ import { ChartDataModelMeta } from './types.js';
2
+ /** 배지 종류(§9.4 통일 문법). / Badge kind (§9.4 unified grammar). */
3
+ export type BadgeKind = 'sampled' | 'aggregated' | 'negativesAbsInPie' | 'pieReducedToFirst' | 'truncatedAxis' | 'engineFallback' | 'unsupportedType';
4
+ /** 무결성 배지 한 건(위치·형태·상호작용은 렌더 계층, 여기선 데이터). / One integrity badge (data only). */
5
+ export interface ProvenanceBadge {
6
+ readonly kind: BadgeKind;
7
+ /** 배지 M(표시)/N(원본) — sampled 에서 채워짐(REQ-T6-810). / Badge M(shown)/N(source). */
8
+ readonly m?: number;
9
+ readonly n?: number;
10
+ /** 로케일 키(t 해석). / Locale key (resolved by t). */
11
+ readonly key: string;
12
+ /** 로케일 파라미터. / Locale params. */
13
+ readonly params?: Readonly<Record<string, string | number>>;
14
+ }
15
+ /** 차트 provenance(scene.meta 동행). / Chart provenance (travels with scene.meta). */
16
+ export interface ChartProvenance {
17
+ readonly badges: readonly ProvenanceBadge[];
18
+ /** 정상(무왜곡) 차트는 배지 0개(§9.3.4 게이트). / An honest (undistorted) chart has 0 badges. */
19
+ readonly clean: boolean;
20
+ }
21
+ /** 추가 변환 플래그(meta 에 없는 절단축·엔진/타입 폴백). / Extra transform flags not in meta. */
22
+ export interface ProvenanceExtra {
23
+ /** line y축 절단(min≠0 opt-in) — 배지 강제(§9.3.1). / Truncated line y-axis (opt-in). */
24
+ truncatedAxis?: boolean;
25
+ /** 외부 엔진 미로드 → builtin 폴백(REQ-T6-812). / External engine fallback. */
26
+ engineFallback?: boolean;
27
+ /** 미지원 차트타입 → builtin 폴백(REQ-T6-812). / Unsupported chart type fallback. */
28
+ unsupportedType?: boolean;
29
+ }
30
+ /**
31
+ * meta(+extra) → provenance 배지 모델. 순수·결정론. 변형이 없으면 clean=true(배지 0).
32
+ * / meta (+extra) → provenance badge model. Pure & deterministic. clean=true (0 badges) when nothing transformed.
33
+ *
34
+ * @param meta - 차트 데이터 모델 메타 / Chart data model meta
35
+ * @param extra - 절단축·엔진/타입 폴백 플래그(선택) / Truncated-axis / engine-type fallback flags (optional)
36
+ * @returns provenance 배지 모델 / Provenance badge model
37
+ */
38
+ export declare function buildProvenance(meta: ChartDataModelMeta, extra?: ProvenanceExtra): ChartProvenance;
39
+ /**
40
+ * 배지 → 표시 문자열(로케일 t 주입). 산발 각주 대신 이 함수를 전 표면 공유(§9.4).
41
+ * / Badge → display string (inject locale t). Shared by all surfaces instead of scattered footnotes.
42
+ *
43
+ * @param badge - 배지 / The badge
44
+ * @param t - 로케일 해석기(키·파라미터 → 문자열). 미주입 시 폴백 영문 / Locale resolver; English fallback when absent
45
+ * @returns 표시 문자열 / Display string
46
+ */
47
+ export declare function badgeText(badge: ProvenanceBadge, t?: (key: string, params?: Record<string, string | number>) => string): string;
@@ -1,24 +1,51 @@
1
1
  /**
2
2
  * F4 — nice-number 축 눈금 스케일(순수 함수, 헤드리스). §8.1(자동검증 대상 수학).
3
+ * / F4 — nice-number axis-tick scaling (pure functions, headless). §8.1 (auto-verified math).
3
4
  *
4
5
  * 표준 Heckbert "Nice Numbers for Graph Labels" 알고리즘. 목표 tick 수(default 6)에 맞춰
5
6
  * step 을 1/2/5×10^n 중에서 선택하고, [min,max] 를 그 step 배수로 확장한다.
7
+ * / The standard Heckbert "Nice Numbers for Graph Labels" algorithm. It picks a step among
8
+ * 1/2/5×10^n to fit a target tick count (default 6) and expands [min,max] to multiples of that step.
6
9
  *
7
10
  * 한계(정직 명시): 이 알고리즘은 min=0 류의 "원점 기준" 범위에서는 매우 안정적으로
8
11
  * tick 5~6개를 낸다(설계서 §8.1 문서화 예시 [0,97]→6 tick 포함). min≠0 인 임의 구간에서는
9
12
  * step 후보가 {1,2,5,10} 로 성기어(coarse) tick 수가 4개나 7개로 튈 수 있다 — 표준 알고리즘의
10
13
  * 알려진 한계이며, 본 구현은 문서화된 대표 입력(§8.1)에 대해서만 5~6 불변식을 보장한다.
14
+ * / Honest limitation: for origin-anchored ranges like min=0 the algorithm very stably yields
15
+ * 5–6 ticks (e.g. the documented §8.1 example [0,97]→6 ticks). For arbitrary ranges with min≠0
16
+ * the coarse {1,2,5,10} step candidates can make the tick count jump to 4 or 7 — a known
17
+ * limitation of the standard algorithm; this implementation guarantees the 5–6 invariant only for
18
+ * the documented representative inputs (§8.1).
11
19
  */
20
+ /** nice-number 스케일 결과(min/max/step 과 tick 배열). / A nice-number scale result (min/max/step and tick array). */
12
21
  export interface NiceScale {
22
+ /** 확장된 최솟값. / Expanded minimum. */
13
23
  min: number;
24
+ /** 확장된 최댓값. / Expanded maximum. */
14
25
  max: number;
26
+ /** tick 간격. / Tick step. */
15
27
  step: number;
28
+ /** tick 값 배열. / Array of tick values. */
16
29
  ticks: number[];
17
30
  }
18
- /** range 를 1/2/5×10^n 중 하나로 반올림한다(round=true: 가장 가까운 값, false: 올림 쪽 느슨한 값). */
31
+ /**
32
+ * range 를 1/2/5×10^n 중 하나로 반올림한다(round=true: 가장 가까운 값, false: 올림 쪽 느슨한 값).
33
+ * / Round a range to one of 1/2/5×10^n (round=true: nearest; false: looser round-up).
34
+ *
35
+ * @param range - 반올림할 범위 크기 / Range magnitude to round
36
+ * @param round - true=가장 가까운 nice 값, false=올림 쪽 / true = nearest nice value, false = round-up side
37
+ * @returns nice 값 / The nice value
38
+ */
19
39
  export declare function niceNum(range: number, round: boolean): number;
20
40
  /**
21
41
  * [dataMin,dataMax] → nice range/step/tick 배열(§8.1). maxTicks 는 목표 tick 수(default 6).
22
42
  * dataMin===dataMax(degenerate) 이면 값 주변으로 인위 확장한다.
43
+ * / [dataMin,dataMax] → nice range/step/tick array (§8.1). maxTicks is the target tick count
44
+ * (default 6). A degenerate dataMin===dataMax is artificially expanded around the value.
45
+ *
46
+ * @param dataMin - 데이터 최솟값 / Data minimum
47
+ * @param dataMax - 데이터 최댓값 / Data maximum
48
+ * @param maxTicks - 목표 tick 수(기본 6) / Target tick count (default 6)
49
+ * @returns nice min/max/step 과 tick 배열 / Nice min/max/step and the tick array
23
50
  */
24
51
  export declare function niceScale(dataMin: number, dataMax: number, maxTicks?: number): NiceScale;
@@ -0,0 +1,102 @@
1
+ import { ChartDataModel, ChartRenderSpec, ChartDataModelMeta, ChartSeries } from './types.js';
2
+ import { ChartGeometry } from './geometry.js';
3
+ import { patternOverlay, dashFor } from './surfaces/pattern-overlay.js';
4
+ /** 색 외 구분 패턴(§9.2). / Redundant (non-color) pattern (§9.2). */
5
+ export type SeriesPattern = NonNullable<ChartSeries['pattern']>;
6
+ /** 텍스트 정렬. / Text alignment. */
7
+ export type TextAlign = 'start' | 'center' | 'end';
8
+ /** 텍스트 기준선. / Text baseline. */
9
+ export type TextBaseline = 'top' | 'middle' | 'bottom';
10
+ /** 원시 드로우명령(타깃 무관). / Primitive draw command (target-agnostic). */
11
+ export type DrawPrim = {
12
+ readonly k: 'rect';
13
+ x: number;
14
+ y: number;
15
+ w: number;
16
+ h: number;
17
+ fill: string;
18
+ pattern?: SeriesPattern;
19
+ } | {
20
+ readonly k: 'polyline';
21
+ pts: ReadonlyArray<readonly [number, number]>;
22
+ stroke: string;
23
+ width: number;
24
+ dash?: readonly number[];
25
+ } | {
26
+ readonly k: 'circle';
27
+ cx: number;
28
+ cy: number;
29
+ r: number;
30
+ fill: string;
31
+ } | {
32
+ readonly k: 'line';
33
+ x1: number;
34
+ y1: number;
35
+ x2: number;
36
+ y2: number;
37
+ stroke: string;
38
+ width: number;
39
+ } | {
40
+ readonly k: 'text';
41
+ x: number;
42
+ y: number;
43
+ s: string;
44
+ fill: string;
45
+ align: TextAlign;
46
+ baseline: TextBaseline;
47
+ font: string;
48
+ } | {
49
+ readonly k: 'arc';
50
+ cx: number;
51
+ cy: number;
52
+ r: number;
53
+ a0: number;
54
+ a1: number;
55
+ fill: string;
56
+ pattern?: SeriesPattern;
57
+ };
58
+ /** 장면 = 배경→축→데이터→마커 순서의 원시명령 + 자기고지 메타. / Scene = ordered prims + self-declaring meta. */
59
+ export interface ChartScene {
60
+ readonly width: number;
61
+ readonly height: number;
62
+ readonly bg: string;
63
+ readonly prims: readonly DrawPrim[];
64
+ readonly geometry: ChartGeometry;
65
+ readonly meta: ChartDataModelMeta;
66
+ }
67
+ /** 렌더 타깃 종류. / Render target kind. */
68
+ export type RenderTargetKind = 'canvas' | 'svg' | 'server';
69
+ /** 장면을 백엔드 원시연산으로 번역하는 humble 어댑터. 로직·판단 없음(§2.3). / Humble scene→backend translator. */
70
+ export interface RenderSurface {
71
+ readonly kind: RenderTargetKind;
72
+ paint(scene: ChartScene): void;
73
+ }
74
+ /**
75
+ * 순수: 완전 기하 → 드로우리스트(§2.2). 색/패턴은 palette 로 확정. **유일한 그림 결정 지점**.
76
+ * / Pure: complete geometry → draw list. Colors/patterns finalized via palette. The sole drawing-decision point.
77
+ *
78
+ * @param model - 차트 데이터 모델 / Chart data model
79
+ * @param spec - 렌더 스펙 / Render spec
80
+ * @param geometry - 공유 기하(computeChartGeometry 산출) / Shared geometry
81
+ * @param hidden - 숨긴 series 인덱스 / Hidden series indices
82
+ * @returns 타깃 무관 장면 / Target-agnostic scene
83
+ */
84
+ export declare function buildChartScene(model: ChartDataModel, spec: ChartRenderSpec, geometry: ChartGeometry, hidden?: ReadonlySet<number>): ChartScene;
85
+ /**
86
+ * 타깃 통일 진입점 — 계산은 공유(geometry+scene), surface 만 분기(§2.4). scene 반환(파리티 골든·hit-test).
87
+ * / Unified render entry — computation shared (geometry+scene), only the surface branches. Returns
88
+ * the scene (parity golden / hit-test).
89
+ *
90
+ * @param model - 차트 데이터 모델 / Chart data model
91
+ * @param spec - 렌더 스펙 / Render spec
92
+ * @param size - 렌더 크기 / Render size
93
+ * @param surface - 타깃 surface(humble) / Target surface (humble)
94
+ * @param hidden - 숨긴 series 인덱스 / Hidden series indices
95
+ * @returns 소비된 장면 / The consumed scene
96
+ */
97
+ export declare function renderChart(model: ChartDataModel, spec: ChartRenderSpec, size: {
98
+ width: number;
99
+ height: number;
100
+ }, surface: RenderSurface, hidden?: ReadonlySet<number>): ChartScene;
101
+ /** scene 텍스처 오버레이 재노출(surface 공유). / Re-export texture overlay for surfaces. */
102
+ export { patternOverlay, dashFor };
@@ -0,0 +1,36 @@
1
+ import { ChartDataModel, ChartRenderSpec } from './types.js';
2
+ import { ChartScene } from './scene.js';
3
+ import { IRasterizer } from './surfaces/ServerRasterSurface.js';
4
+ import { ChartProvenance, ProvenanceExtra } from './provenance.js';
5
+ /** 서버 렌더 옵션. / Server render options. */
6
+ export interface ServerRenderOptions {
7
+ /** PNG 픽셀화 주입(없으면 png 미산출, SVG 1급). / PNG rasterizer injection (no png without it). */
8
+ rasterizer?: IRasterizer;
9
+ /** DPR(서버 스케일). 기본 1. / DPR (server scale). Default 1. */
10
+ dpr?: number;
11
+ /** 숨긴 series 인덱스. / Hidden series indices. */
12
+ hidden?: ReadonlySet<number>;
13
+ /** 절단축·엔진/타입 폴백 배지 플래그. / Truncated-axis / engine-type fallback badge flags. */
14
+ provenance?: ProvenanceExtra;
15
+ }
16
+ /** 서버 렌더 결과(§2.5). png 는 rasterizer 주입 시에만. / Server render result. png only with a rasterizer. */
17
+ export interface ServerRenderResult {
18
+ readonly scene: ChartScene;
19
+ readonly svg: string;
20
+ readonly png?: Uint8Array;
21
+ readonly provenance: ChartProvenance;
22
+ }
23
+ /**
24
+ * 서버 헤드리스 렌더 — SVG·scene·provenance 항상 산출, PNG 는 opt-in. 클라이언트와 동일 scene.
25
+ * / Server headless render — always yields SVG/scene/provenance; PNG is opt-in. Same scene as client.
26
+ *
27
+ * @param spec - 렌더 스펙(타입·테마·포맷) / Render spec (type, theme, format)
28
+ * @param model - 차트 데이터 모델 / Chart data model
29
+ * @param size - 렌더 크기 / Render size
30
+ * @param opts - rasterizer·dpr·hidden·provenance(선택) / rasterizer·dpr·hidden·provenance (optional)
31
+ * @returns scene·svg·(png?)·provenance / scene·svg·(png?)·provenance
32
+ */
33
+ export declare function renderChartServer(spec: ChartRenderSpec, model: ChartDataModel, size: {
34
+ width: number;
35
+ height: number;
36
+ }, opts?: ServerRenderOptions): ServerRenderResult;
@@ -0,0 +1,48 @@
1
+ import { ChartScene, RenderSurface } from '../scene.js';
2
+ type Ctx = {
3
+ setTransform(a: number, b: number, c: number, d: number, e: number, f: number): void;
4
+ clearRect(x: number, y: number, w: number, h: number): void;
5
+ beginPath(): void;
6
+ moveTo(x: number, y: number): void;
7
+ lineTo(x: number, y: number): void;
8
+ arc(cx: number, cy: number, r: number, a0: number, a1: number): void;
9
+ closePath(): void;
10
+ fill(): void;
11
+ stroke(): void;
12
+ fillRect(x: number, y: number, w: number, h: number): void;
13
+ fillText(s: string, x: number, y: number): void;
14
+ save(): void;
15
+ restore(): void;
16
+ clip(): void;
17
+ rect(x: number, y: number, w: number, h: number): void;
18
+ setLineDash(d: number[]): void;
19
+ fillStyle: string;
20
+ strokeStyle: string;
21
+ lineWidth: number;
22
+ font: string;
23
+ textAlign: string;
24
+ textBaseline: string;
25
+ };
26
+ /**
27
+ * canvas 2D 로 scene 을 래스터화한다. constructor 에 canvas·dpr 을 주입받고, paint 시 ctx 를
28
+ * 해소한다(없으면 no-op). / Rasterizes a scene onto a canvas 2D context. Injects canvas/dpr;
29
+ * resolves the ctx at paint time (no-op if absent).
30
+ */
31
+ export declare class CanvasSurface implements RenderSurface {
32
+ readonly kind: "canvas";
33
+ private _canvas;
34
+ private _dpr;
35
+ /**
36
+ * @param canvas - 렌더 대상 canvas(주입) / Target canvas (injected)
37
+ * @param dpr - devicePixelRatio(호스트 주입, 헤드리스 순수) / devicePixelRatio (host-injected, headless-pure)
38
+ */
39
+ constructor(canvas: {
40
+ width: number;
41
+ height: number;
42
+ getContext?: (id: string) => Ctx | null;
43
+ }, dpr?: number);
44
+ paint(scene: ChartScene): void;
45
+ private _prim;
46
+ private _overlay;
47
+ }
48
+ export {};
@@ -0,0 +1,26 @@
1
+ import { ChartScene, RenderSurface } from '../scene.js';
2
+ /** 주입형 래스터라이저 SPI(옵트인 애드온). scene 또는 SVG→PNG. / Injected rasterizer SPI (opt-in add-on). */
3
+ export interface IRasterizer {
4
+ /** scene 을 PNG 바이트로 래스터화(sharp/pngjs/resvg 등 호스트 제공). / Rasterize scene → PNG bytes. */
5
+ rasterize(scene: ChartScene): Uint8Array;
6
+ }
7
+ /**
8
+ * 서버 PNG surface — DOM/canvas 전역 없이 동작. rasterizer 미주입 시 toPNG()=throw.
9
+ * / Server PNG surface — works with no DOM/canvas globals. If no rasterizer, toPNG() throws.
10
+ */
11
+ export declare class ServerRasterSurface implements RenderSurface {
12
+ readonly kind: "server";
13
+ private _rasterizer;
14
+ private _scene;
15
+ /**
16
+ * @param rasterizer - 주입 래스터라이저(없으면 PNG 미산출) / Injected rasterizer (no PNG without it)
17
+ */
18
+ constructor(rasterizer?: IRasterizer);
19
+ paint(scene: ChartScene): void;
20
+ /**
21
+ * 주입 rasterizer 로 PNG 산출(코어 미내장). 미주입/미paint 시 throw(불변식4).
22
+ * / Produce PNG via the injected rasterizer (not embedded in core). Throws if not injected / not painted.
23
+ * @returns PNG 바이트 / PNG bytes
24
+ */
25
+ toPNG(): Uint8Array;
26
+ }
@@ -0,0 +1,24 @@
1
+ import { ChartScene, RenderSurface } from '../scene.js';
2
+ /**
3
+ * scene 을 SVG 문자열로 래스터화하는 humble surface. `paint(scene)` 후 `toString()` 으로 완성 마크업.
4
+ * provenance(§9.4)는 `<title>/<desc>` 로 동행한다(REQ-T6-811).
5
+ * / Humble surface that rasterizes a scene into an SVG string. After `paint(scene)`, `toString()`
6
+ * yields the full markup. Provenance travels along in `<title>/<desc>` (REQ-T6-811).
7
+ */
8
+ export declare class SvgSurface implements RenderSurface {
9
+ readonly kind: "svg";
10
+ private _dpr;
11
+ private _out;
12
+ /** @param opts.dpr - viewBox 배율(선택, 기본 1) / viewBox scale (optional, default 1) */
13
+ constructor(opts?: {
14
+ dpr?: number;
15
+ });
16
+ paint(scene: ChartScene): void;
17
+ /** 완성 <svg> 마크업(RT-803 서버 SVG 출력). / Full <svg> markup (RT-803 server SVG output). */
18
+ toString(): string;
19
+ private _desc;
20
+ private _prim;
21
+ private _overlay;
22
+ /** 파이 슬라이스 path(중심→호→닫기). / Pie-slice path (center → arc → close). */
23
+ private _arcPath;
24
+ }
@@ -0,0 +1,24 @@
1
+ import { SeriesPattern } from '../scene.js';
2
+ /** 오버레이 선분 [x1,y1,x2,y2]. / Overlay line segment. */
3
+ export type OverlaySeg = readonly [number, number, number, number];
4
+ /** 오버레이 점 [cx,cy,r]. / Overlay dot. */
5
+ export type OverlayDot = readonly [number, number, number];
6
+ /** 텍스처 오버레이 결과(선분·점). / Texture overlay result (segments + dots). */
7
+ export interface PatternOverlay {
8
+ readonly segs: readonly OverlaySeg[];
9
+ readonly dots: readonly OverlayDot[];
10
+ }
11
+ /**
12
+ * 사각형 안의 색약 안전 텍스처 좌표(§9.2). solid/undefined → 빈 오버레이.
13
+ * / Colorblind-safe texture coordinates inside a rect. solid/undefined → empty overlay.
14
+ *
15
+ * @param x - 사각형 좌상단 x / Rect top-left x
16
+ * @param y - 사각형 좌상단 y / Rect top-left y
17
+ * @param w - 너비 / Width
18
+ * @param h - 높이 / Height
19
+ * @param pattern - 패턴 종류 / Pattern kind
20
+ * @returns 텍스처 선분·점 좌표 / Texture segments and dots
21
+ */
22
+ export declare function patternOverlay(x: number, y: number, w: number, h: number, pattern: SeriesPattern | undefined): PatternOverlay;
23
+ /** line/area 대시 배열(현 CanvasAdapter.dashFor 와 동일). / Line dash array (matches CanvasAdapter.dashFor). */
24
+ export declare function dashFor(pattern: SeriesPattern | undefined): number[];
@@ -1,10 +1,20 @@
1
1
  import { CellRange } from '../types.js';
2
2
  /**
3
- * Phase1 MVP = 'bar'|'line'. 나머지는 Phase2/3 예약(타입만 선언, 미구현).
3
+ * 그리드 데이터를 어떤 모양의 차트로 그릴지 고르는 값. / Picks which shape of chart to draw the
4
+ * grid data as.
4
5
  *
5
- * ⚠️ 'bar-stacked': 공개 타입으로 노출되어 있으나 내장(builtin-canvas) 렌더러는 현재 스택
6
- * 누적을 구현하지 않는다 — 지정해도 'bar-grouped'와 동일하게 그룹형(side-by-side)으로
7
- * 폴백 렌더된다(CanvasAdapter._computeGeometry). 하위호환을 위해 타입 자체는 유지한다.
6
+ * 현재(Phase1 MVP) 실제로 렌더되는 값은 'bar'|'line' 뿐이다. 나머지는 Phase2/3 를 위해 타입만
7
+ * 미리 선언해 둔 예약값이며 아직 구현되지 않았다.
8
+ * / Right now (Phase1 MVP) only 'bar' and 'line' actually render. The rest are reserved values —
9
+ * the type exists for Phase2/3 but nothing implements them yet.
10
+ *
11
+ * ⚠️ 'bar-stacked': 공개 타입으로는 노출돼 있지만, 내장(builtin-canvas) 렌더러는 아직 누적
12
+ * 스택을 그리지 못한다 — 지정해도 'bar-grouped'와 똑같이 그룹형(막대를 나란히)으로 대신
13
+ * 그려진다. 하위 호환을 위해(이미 이 값을 쓰는 코드가 깨지지 않도록) 타입 자체는 남겨 둔다.
14
+ * / ⚠️ 'bar-stacked': exposed as a public type, but the built-in canvas renderer can't draw a
15
+ * stacked bar yet — specifying it falls back to the same grouped (side-by-side) rendering as
16
+ * 'bar-grouped'. The type itself is kept for backward compatibility, so existing code using this
17
+ * value doesn't break.
8
18
  */
9
19
  export type ChartType = 'bar' | 'line' | 'area' | 'pie' | 'doughnut' | 'bar-stacked' | 'bar-grouped';
10
20
  /** 시리즈(컬럼) 명세. / Series (column) spec. */
@@ -20,7 +30,18 @@ export interface ChartSeriesSpec {
20
30
  /** 시리즈별 렌더 타입(혼합 차트). / Per-series render type (mixed charts). */
21
31
  type?: 'bar' | 'line' | 'area';
22
32
  }
23
- /** 차트 데이터 소스(범위/선택/체크/전체/컬럼 지정). / Chart data source (range/selection/checked/all/explicit columns). */
33
+ /**
34
+ * 차트 파이프라인의 첫 단계 — "그리드의 어느 데이터를 그릴 것인가"를 고른다.
35
+ * / The first stage of the chart pipeline — picks which grid data to draw.
36
+ *
37
+ * `'range'`(지정 범위)·`'selection'`(현재 드래그 선택)·`'checked'`(체크된 행)·`'all'`(전체
38
+ * 데이터) 는 "사용자가 화면에서 고른 것을 그대로 차트로" 만들 때 쓰고, `'columns'` 는 화면 선택과
39
+ * 무관하게 카테고리/시리즈 컬럼을 코드로 직접 지정하고 싶을 때 쓴다.
40
+ * / `'range'` (a given cell range), `'selection'` (the current drag selection), `'checked'`
41
+ * (checked rows), and `'all'` (the whole dataset) turn whatever the user picked on screen
42
+ * straight into a chart. `'columns'` is for when you want to specify the category/series columns
43
+ * in code, independent of any on-screen selection.
44
+ */
24
45
  export type ChartSource = {
25
46
  kind: 'range';
26
47
  range?: CellRange;
@@ -56,7 +77,11 @@ export interface ChartSeries {
56
77
  data: Array<number | null>;
57
78
  /** 시리즈 색. / Series color. */
58
79
  color?: string;
59
- /** 색 외 구분(HANMS-19). / Non-color distinction (HANMS-19). */
80
+ /** 색만으로 시리즈를 구분하기 어려운 사용자(색약 등)를 위해, 색과 함께(또는 색 대신) 채움
81
+ * 무늬로도 시리즈를 구분한다. 'solid'=무늬 없음(기본), 'hatch'=사선, 'dot'=점, 'cross'=십자.
82
+ * / A fill pattern that distinguishes series by shape, not just color — for viewers who can't
83
+ * rely on color alone (color-vision deficiency, etc.). 'solid' = no pattern (default),
84
+ * 'hatch' = diagonal lines, 'dot' = dots, 'cross' = crosshatch. */
60
85
  pattern?: 'solid' | 'hatch' | 'dot' | 'cross';
61
86
  }
62
87
  /** 차트 데이터 모델 메타(출처·샘플링·집계 배지 정보). / Chart data model meta (source, sampling, aggregation badge info). */
@@ -65,11 +90,15 @@ export interface ChartDataModelMeta {
65
90
  sourceKind: ChartSource['kind'];
66
91
  /** 원본 포인트(행) 수. / Original point (row) count. */
67
92
  total: number;
68
- /** LTTB 다운샘플 또는 category 집계로 축약됐는가 → 배지(§C). / Whether reduced by LTTB downsample or category aggregation → badge (§C). */
93
+ /** 원본 데이터가 LTTB 다운샘플링이나 카테고리 집계로 축약됐는가. true 면 화면에 그려진 값이
94
+ * 원본 그대로가 아니라는 뜻이므로, 이 값을 보고 UI에서 축약 사실을 배지로 고지해야 한다.
95
+ * / Whether the original data was reduced via LTTB downsampling or category aggregation. When
96
+ * true, what's drawn on screen isn't the raw data verbatim — the UI should surface a badge
97
+ * using this flag so the reduction isn't hidden from the viewer. */
69
98
  sampled: boolean;
70
- /** 다운샘플 전 포인트 수. / Point count before downsampling. */
99
+ /** 다운샘플링 전 포인트 수. / Point count before downsampling. */
71
100
  sampledFrom?: number;
72
- /** 다운샘플 후 포인트 수. / Point count after downsampling. */
101
+ /** 다운샘플링 후 포인트 수. / Point count after downsampling. */
73
102
  sampledTo?: number;
74
103
  /** 적용된 집계 연산. / Applied aggregation op. */
75
104
  aggregatedOp?: 'sum' | 'avg' | 'count' | 'min' | 'max' | 'custom';
@@ -77,7 +106,11 @@ export interface ChartDataModelMeta {
77
106
  pieReducedToFirst?: boolean;
78
107
  /** pie 에서 음수를 절댓값 처리했는가. / Whether pie used absolute values for negatives. */
79
108
  negativesAbsInPie?: boolean;
80
- /** SR 폴백 — extractor 가 렌더러와 무관하게 항상 채운다(§B 하드 게이트). / SR fallback — always filled by the extractor regardless of renderer (§B hard gate). */
109
+ /** 스크린리더 사용자를 위한 표 형태의 텍스트 등가물. 어떤 렌더 엔진(내장 canvas·외부 lib)을
110
+ * 쓰든 추출(extractor) 단계에서 항상 채워지므로, 렌더러가 접근성을 신경 쓰지 않아도 이 값은
111
+ * 항상 존재한다. / A table-shaped text alternative for screen-reader users. It's always filled
112
+ * during extraction regardless of which render engine (built-in canvas or an external lib) is
113
+ * used, so it's guaranteed to exist even if the renderer itself doesn't handle accessibility. */
81
114
  a11yTable: A11yTableModel;
82
115
  }
83
116
  /** 헤드리스 차트 데이터 모델(추출 산출물). / Headless chart data model (extraction output). */
@@ -154,8 +187,26 @@ export interface ChartPoint {
154
187
  rowId?: string;
155
188
  }
156
189
  /**
157
- * 차트 렌더 어댑터(교체 seam) — 내장 canvas / 외부 lib 백엔드를 통일된 인터페이스로 감싼다.
158
- * / Chart render adapter (swap seam) — wraps the built-in canvas / external-lib backends behind one interface.
190
+ * 차트 렌더 어댑터(교체 seam) — 내장 canvas 렌더러와 외부 차트 라이브러리(ECharts 등) 백엔드를
191
+ * 하나의 공통 인터페이스로 감싼다. 내장 렌더러로는 부족해서 다른 차트 라이브러리로 실제 그리는
192
+ * 부분만 바꿔치기하고 싶을 때, 이 인터페이스를 구현해 `ChartConfig.engine`에 넘긴다.
193
+ * / Chart render adapter (swap seam) — wraps the built-in canvas renderer and external chart
194
+ * library backends (e.g. ECharts) behind one common interface. Implement this when the built-in
195
+ * renderer isn't enough and you want to swap in a different charting library for the actual
196
+ * drawing, then pass it via `ChartConfig.engine`.
197
+ *
198
+ * @example
199
+ * const myAdapter: ChartAdapter = {
200
+ * id: 'my-echarts-adapter',
201
+ * // 차트 라이브러리 인스턴스 생성 / create the chart-lib instance
202
+ * async init(host, spec) { echartsInstance = echarts.init(host); },
203
+ * // model.categories/series 를 라이브러리 포맷으로 변환해 그리기 / map the model into the lib's format and draw
204
+ * render(model, spec) { echartsInstance.setOption(toEchartsOption(model, spec)); },
205
+ * // 라이브러리 resize 호출 / call the lib's resize
206
+ * resize(w, h) { echartsInstance.resize({ width: w, height: h }); },
207
+ * // 라이브러리 인스턴스 정리 / tear down the lib instance
208
+ * destroy() { echartsInstance.dispose(); },
209
+ * };
159
210
  */
160
211
  export interface ChartAdapter {
161
212
  /** 어댑터 식별자. / Adapter identifier. */
@@ -173,19 +224,29 @@ export interface ChartAdapter {
173
224
  /** 어댑터 정리. / Tear down the adapter. */
174
225
  destroy(): void;
175
226
  }
176
- /** createChart 반환 핸들(§6). 구현은 ChartManager. / Handle returned by createChart (§6); implemented by ChartManager. */
227
+ /** `grid.createChart()`가 반환하는, 살아있는 차트를 다루는 핸들. 실제 구현체는 ChartManager.
228
+ * 이 핸들로 타입 전환·갱신·이미지 추출·파기까지 차트의 생애주기 전체를 조작한다.
229
+ * / The handle returned by `grid.createChart()` for controlling a live chart; implemented by
230
+ * ChartManager. Use it to change type, refresh, export an image, and destroy — the chart's
231
+ * whole lifecycle. */
177
232
  export interface ChartInstance {
178
233
  /** 차트 인스턴스 id. / Chart instance id. */
179
234
  readonly id: string;
180
235
  /** 설정 패치 후 갱신. / Patch config and update. */
181
236
  update(patch?: Partial<ChartConfig>): void;
182
237
  /**
183
- * 모델을 재추출하고 렌더 스펙(테마 포함)을 재스냅샷해 재렌더한다(§5.3). 그리드는 테마 변경
184
- * 이벤트를 발행하지 않으므로(`setTheme`/`setThemeVar`는 CSS 만 갱신) 다크모드 토글처럼 데이터
185
- * 변화 없는 순수 테마 전환 후에는, 열려 있는 각 차트에 대해 이 메서드를 호출해야 새 테마
186
- * (색·글꼴·팔레트)가 재적용된다. `update()`/`setType()`도 내부적으로 동일 경로를 탄다.
238
+ * 모델을 재추출하고 렌더 스펙(테마 포함)을 다시 계산해 재렌더한다.
239
+ * / Re-extract the model and recompute the render spec (incl. theme), then re-render.
240
+ *
241
+ * 그리드는 테마가 바뀌어도 별도 이벤트를 발행하지 않는다(`setTheme`/`setThemeVar`는 CSS만
242
+ * 갱신). 그래서 다크모드 토글처럼 데이터는 그대로고 테마만 바뀐 경우, 열려 있는 각 차트에
243
+ * 대해 이 메서드를 직접 호출해야 새 테마(색·글꼴·팔레트)가 반영된다. `update()`/`setType()`도
244
+ * 내부적으로 이 경로를 그대로 탄다.
245
+ * / The grid doesn't emit a dedicated event when only the theme changes (`setTheme`/
246
+ * `setThemeVar` update CSS only). So after a pure theme switch with no data change — e.g. a
247
+ * dark-mode toggle — call this on each open chart to apply the new theme (colors, fonts,
248
+ * palette). `update()` and `setType()` internally follow the same path.
187
249
  */
188
- /** 모델을 재추출하고 렌더 스펙(테마 포함)을 재스냅샷해 재렌더. / Re-extract the model and re-snapshot the render spec (incl. theme), then re-render. */
189
250
  refresh(): void;
190
251
  /** 차트 타입 변경. / Change the chart type. */
191
252
  setType(type: ChartType): void;
@@ -198,7 +259,11 @@ export interface ChartInstance {
198
259
  /** 차트 이벤트 리스너 등록. / Register a chart event listener. */
199
260
  on(ev: 'chartRender' | 'chartPointClick', cb: (...a: any[]) => void): void;
200
261
  }
201
- /** GridOptions.chart 로 중첩되는 전역 옵션(C5.1, 최상위 flat 키 금지). / Global options nested under GridOptions.chart (C5.1; no top-level flat keys). */
262
+ /** `GridOptions.chart`에 중첩해서 넣는, 그리드 전체에 적용되는 차트 기본값. 그리드 인스턴스를
263
+ * 만들 때 한 번 설정해 두면 이후 `createChart()` 호출마다 반복하지 않아도 되는 공통값(기본
264
+ * 엔진·팔레트·포인트 상한 등)이다. / Chart defaults applied grid-wide, nested under
265
+ * `GridOptions.chart`. Set once when constructing the grid, and every later `createChart()` call
266
+ * inherits the shared defaults (default engine, palette, point cap, etc.) without repeating them. */
202
267
  export interface ChartGlobalOptions {
203
268
  /** 차트 기능 활성화. / Enable the chart feature. */
204
269
  enabled?: boolean;
@@ -208,7 +273,7 @@ export interface ChartGlobalOptions {
208
273
  defaultType?: ChartType;
209
274
  /** 기본 배치 방식. / Default placement. */
210
275
  placement?: 'docked' | 'modal' | 'inline' | 'floating';
211
- /** 렌더 포인트 상한(초과 시 다운샘플). / Max render points (downsample above this). */
276
+ /** 렌더 포인트 상한(초과 시 다운샘플링). / Max render points (downsample above this). */
212
277
  maxPoints?: number;
213
278
  /** live 갱신 디바운스(ms). / Debounce for live updates (ms). */
214
279
  debounceMs?: number;
@@ -236,7 +301,23 @@ export interface ChartGlobalOptions {
236
301
  id: string;
237
302
  }) => void;
238
303
  }
239
- /** createChart() 공개 설정(§6). / Public config for createChart() (§6). */
304
+ /**
305
+ * `grid.createChart(config)`에 넘기는 공개 설정. 어떤 데이터를(source) 어떤 모양으로(type)
306
+ * 그릴지가 필수고, 나머지는 배치·엔진·꾸밈(제목/범례/축 등)을 위한 선택 옵션이다.
307
+ * / The public config passed to `grid.createChart(config)`. Only which data (source) and what
308
+ * shape (type) to draw are required; the rest are optional placement/engine/decoration
309
+ * (title, legend, axis, etc.) settings.
310
+ *
311
+ * @example
312
+ * const chart = grid.createChart({
313
+ * source: { kind: 'all' },
314
+ * type: 'bar',
315
+ * category: 'region',
316
+ * series: ['sales'],
317
+ * placement: 'inline',
318
+ * mount: document.querySelector('#chart-host')!,
319
+ * });
320
+ */
240
321
  export interface ChartConfig {
241
322
  /** 데이터 소스. / Data source. */
242
323
  source: ChartSource;
@@ -0,0 +1,51 @@
1
+ import { ICommand, ICommandCtx } from './ICommand.js';
2
+ import { CommandStack } from './CommandStack.js';
3
+ import { DirtyTracker, MutationGuard, AuditLog } from './support.js';
4
+ /** CommandBus 협력자(전부 옵션 — 기본 구현 주입). / CommandBus collaborators (all optional — defaults injected). */
5
+ export interface CommandBusDeps<T = any> {
6
+ readonly ctx: ICommandCtx<T>;
7
+ stack?: CommandStack<T>;
8
+ audit?: AuditLog;
9
+ dirty?: DirtyTracker;
10
+ guard?: MutationGuard;
11
+ /** 자동저장/협업/감사 구독 fan-out. / Fan-out for autosave/collaboration/audit subscribers. */
12
+ emit?: (event: 'command', cmd: ICommand<T>) => void;
13
+ }
14
+ /**
15
+ * 유일한 쓰기 진입점. 이벤트 오케스트레이션(DD-08/896)이 UI 이벤트를 커맨드로 번역해 여기로 보낸다.
16
+ * / The sole write entry point. Event orchestration (DD-08/896) translates UI events into commands here.
17
+ */
18
+ export declare class CommandBus<T = any> {
19
+ private readonly _ctx;
20
+ private readonly _stack;
21
+ private readonly _audit;
22
+ private readonly _dirty;
23
+ private readonly _guard;
24
+ private readonly _emit;
25
+ private _macro;
26
+ private _macroLabel;
27
+ constructor(deps: CommandBusDeps<T>);
28
+ get stack(): CommandStack<T>;
29
+ get audit(): AuditLog;
30
+ get dirty(): DirtyTracker;
31
+ get guard(): MutationGuard;
32
+ /**
33
+ * 커맨드 실행: do → 스택 push(coalesce 시도) → audit → dirty → emit. 매크로 녹화 중이면 스택 대신
34
+ * 프레임에 수집(그대로 실행됨). / Execute a command; while recording a macro, collect into the frame instead of the stack.
35
+ */
36
+ dispatch(cmd: ICommand<T>): void;
37
+ /** 되돌리기: 스택에서 꺼내 undo 재적용. / Undo: pop and apply undo. */
38
+ undo(): boolean;
39
+ /** 다시하기: 스택에서 꺼내 do 재적용. / Redo: pop and re-apply do. */
40
+ redo(): boolean;
41
+ canUndo(): boolean;
42
+ canRedo(): boolean;
43
+ /** 매크로 녹화 시작 — 이후 dispatch 는 프레임에 수집(실행은 됨). / Begin macro recording. */
44
+ beginMacro(label: string): void;
45
+ /** 매크로 중지 — 수집분을 CompositeCommand 로 접어 단일 undo 단위로 스택에 등록. / End macro; fold into one undo unit. */
46
+ endMacro(): void;
47
+ /** 트랜잭션 배치 — body 안의 dispatch 를 하나의 undo 단위로. 예외 시에도 endMacro 로 닫는다. / Transaction batch. */
48
+ transact(label: string, body: () => void): void;
49
+ /** 녹화 중 여부. / Whether a macro is being recorded. */
50
+ get recording(): boolean;
51
+ }