open-grid 1.2.1 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (251) hide show
  1. package/CHANGELOG.md +376 -365
  2. package/dist/{OpenGrid-0r_543Kj.cjs → OpenGrid-B7m7ei7f.cjs} +1222 -1029
  3. package/dist/{OpenGrid-HmhGVC2V.js → OpenGrid-CeUdO_fM.js} +1613 -1418
  4. package/dist/index-CeJ-0-80.cjs +260 -0
  5. package/dist/index-DnarQ4eR.js +266 -0
  6. package/dist/index-DrCPRuYi.js +548 -0
  7. package/dist/index-JjfWY3Bt.cjs +520 -0
  8. package/dist/open-grid-base.css +12 -1
  9. package/dist/open-grid-react.cjs +1 -1
  10. package/dist/open-grid-react.js +1 -1
  11. package/dist/open-grid-vue.cjs +7 -7
  12. package/dist/open-grid-vue.js +2 -2
  13. package/dist/open-grid.cjs +1 -1
  14. package/dist/open-grid.js +2 -2
  15. package/dist/types/bench/perf.d.ts +14 -8
  16. package/dist/types/core/AppearanceResolver.d.ts +98 -11
  17. package/dist/types/core/CFRenderBridge.d.ts +13 -0
  18. package/dist/types/core/CellTypeRegistry.d.ts +24 -0
  19. package/dist/types/core/ColumnLayout.d.ts +100 -2
  20. package/dist/types/core/CrossGridMapper.d.ts +43 -5
  21. package/dist/types/core/DataLayer.d.ts +210 -15
  22. package/dist/types/core/DragVisuals.d.ts +33 -4
  23. package/dist/types/core/EventEmitter.d.ts +54 -0
  24. package/dist/types/core/FormulaEngine.d.ts +15 -4
  25. package/dist/types/core/GridRenderer.d.ts +143 -10
  26. package/dist/types/core/GroupEngine.d.ts +68 -10
  27. package/dist/types/core/MathUtils.d.ts +58 -5
  28. package/dist/types/core/MergeEngine.d.ts +45 -10
  29. package/dist/types/core/OGDecimal.d.ts +144 -13
  30. package/dist/types/core/OpenGrid.d.ts +99 -0
  31. package/dist/types/core/PivotEngine.d.ts +37 -0
  32. package/dist/types/core/RowDragDrop.d.ts +52 -6
  33. package/dist/types/core/SkinRegistry.d.ts +4 -0
  34. package/dist/types/core/TreeEngine.d.ts +60 -6
  35. package/dist/types/core/VirtualScroll.d.ts +64 -0
  36. package/dist/types/core/a11y/AccessibilityAdapter.d.ts +103 -0
  37. package/dist/types/core/a11y/AriaIntent.d.ts +34 -0
  38. package/dist/types/core/a11y/KeyboardInteractionModel.d.ts +64 -0
  39. package/dist/types/core/a11y/LiveRegionController.d.ts +89 -0
  40. package/dist/types/core/a11y/OverlayStack.d.ts +36 -0
  41. package/dist/types/core/a11y/VisualEquivRegistry.d.ts +37 -0
  42. package/dist/types/core/a11y/index.d.ts +13 -0
  43. package/dist/types/core/a11y/ports.d.ts +24 -0
  44. package/dist/types/core/appearance/Appearance.d.ts +68 -0
  45. package/dist/types/core/appearance/AppearanceAxis.d.ts +94 -0
  46. package/dist/types/core/appearance/AppearanceComposer.d.ts +45 -0
  47. package/dist/types/core/appearance/AppearanceProvider.d.ts +50 -0
  48. package/dist/types/core/appearance/AppearanceView.d.ts +51 -0
  49. package/dist/types/core/appearance/DensityRegistry.d.ts +36 -0
  50. package/dist/types/core/appearance/ResolvedAppearanceSnapshot.d.ts +84 -0
  51. package/dist/types/core/appearance/TextureRegistry.d.ts +32 -0
  52. package/dist/types/core/appearance/ThemeMetaRegistry.d.ts +67 -0
  53. package/dist/types/core/appearance/axisAdapters.d.ts +37 -0
  54. package/dist/types/core/appearance/defaults.d.ts +10 -0
  55. package/dist/types/core/appearance/index.d.ts +20 -0
  56. package/dist/types/core/appearance/tokenCatalog.d.ts +30 -0
  57. package/dist/types/core/cf/CFEngine.d.ts +56 -0
  58. package/dist/types/core/cf/CFEvaluator.d.ts +24 -0
  59. package/dist/types/core/cf/CFRule.d.ts +127 -0
  60. package/dist/types/core/cf/ColorScale.d.ts +49 -0
  61. package/dist/types/core/cf/InkResolver.d.ts +33 -0
  62. package/dist/types/core/cf/appearance.d.ts +20 -0
  63. package/dist/types/core/cf/encoders.d.ts +61 -0
  64. package/dist/types/core/cf/eval-types.d.ts +93 -0
  65. package/dist/types/core/cf/index.d.ts +21 -0
  66. package/dist/types/core/cf/lineage.d.ts +32 -0
  67. package/dist/types/core/cf/predicates.d.ts +27 -0
  68. package/dist/types/core/cf/serialize.d.ts +46 -0
  69. package/dist/types/core/chart/CanvasAdapter.d.ts +50 -1
  70. package/dist/types/core/chart/DataExtractor.d.ts +53 -12
  71. package/dist/types/core/chart/a11y.d.ts +22 -0
  72. package/dist/types/core/chart/chart-type-registry.d.ts +53 -0
  73. package/dist/types/core/chart/downsample-report.d.ts +36 -0
  74. package/dist/types/core/chart/downsample.d.ts +26 -1
  75. package/dist/types/core/chart/engine/ChartEngineRegistry.d.ts +52 -0
  76. package/dist/types/core/chart/geometry.d.ts +96 -0
  77. package/dist/types/core/chart/hittest.d.ts +21 -3
  78. package/dist/types/core/chart/palette.d.ts +96 -12
  79. package/dist/types/core/chart/parity.d.ts +12 -0
  80. package/dist/types/core/chart/provenance.d.ts +47 -0
  81. package/dist/types/core/chart/scales.d.ts +28 -1
  82. package/dist/types/core/chart/scene.d.ts +102 -0
  83. package/dist/types/core/chart/server.d.ts +36 -0
  84. package/dist/types/core/chart/surfaces/CanvasSurface.d.ts +48 -0
  85. package/dist/types/core/chart/surfaces/ServerRasterSurface.d.ts +26 -0
  86. package/dist/types/core/chart/surfaces/SvgSurface.d.ts +24 -0
  87. package/dist/types/core/chart/surfaces/pattern-overlay.d.ts +24 -0
  88. package/dist/types/core/command/CommandBus.d.ts +51 -0
  89. package/dist/types/core/command/CommandRegistry.d.ts +43 -0
  90. package/dist/types/core/command/CommandStack.d.ts +38 -0
  91. package/dist/types/core/command/ICommand.d.ts +110 -0
  92. package/dist/types/core/command/commands/CellWriteCommand.d.ts +32 -0
  93. package/dist/types/core/command/commands/CompositeCommand.d.ts +17 -0
  94. package/dist/types/core/command/commands/RowCommands.d.ts +39 -0
  95. package/dist/types/core/command/index.d.ts +9 -0
  96. package/dist/types/core/command/support.d.ts +51 -0
  97. package/dist/types/core/coordinate/ColumnMetrics.d.ts +30 -0
  98. package/dist/types/core/coordinate/CoordinateKernel.d.ts +88 -0
  99. package/dist/types/core/coordinate/FrozenPanes.d.ts +29 -0
  100. package/dist/types/core/coordinate/MergeSourceAdapter.d.ts +18 -0
  101. package/dist/types/core/coordinate/NodeBudget.d.ts +33 -0
  102. package/dist/types/core/coordinate/ResizeGovernor.d.ts +50 -0
  103. package/dist/types/core/coordinate/RowMetrics.d.ts +37 -0
  104. package/dist/types/core/coordinate/ViewPermutation.d.ts +23 -0
  105. package/dist/types/core/coordinate/index.d.ts +10 -0
  106. package/dist/types/core/coordinate/ports.d.ts +45 -0
  107. package/dist/types/core/coordinate/types.d.ts +76 -0
  108. package/dist/types/core/detail/DetailGlyph.d.ts +42 -7
  109. package/dist/types/core/detail/DetailSplice.d.ts +42 -11
  110. package/dist/types/core/detail/DetailState.d.ts +80 -11
  111. package/dist/types/core/detail/SubgridCache.d.ts +72 -10
  112. package/dist/types/core/detail/index.d.ts +8 -0
  113. package/dist/types/core/domain/AggregateResult.d.ts +54 -0
  114. package/dist/types/core/domain/CellAddress.d.ts +61 -0
  115. package/dist/types/core/domain/CellValueAccess.d.ts +29 -0
  116. package/dist/types/core/domain/Delta.d.ts +37 -0
  117. package/dist/types/core/domain/DomainValue.d.ts +80 -0
  118. package/dist/types/core/domain/Missing.d.ts +65 -0
  119. package/dist/types/core/domain/Money.d.ts +42 -0
  120. package/dist/types/core/domain/NormalizationBasis.d.ts +47 -0
  121. package/dist/types/core/domain/Plain.d.ts +45 -0
  122. package/dist/types/core/domain/Quantity.d.ts +32 -0
  123. package/dist/types/core/domain/Ratios.d.ts +100 -0
  124. package/dist/types/core/domain/ThresholdSet.d.ts +46 -0
  125. package/dist/types/core/domain/ValueType.d.ts +71 -0
  126. package/dist/types/core/domain/rounding.d.ts +25 -0
  127. package/dist/types/core/domain/strategies.d.ts +38 -0
  128. package/dist/types/core/editors/DateEditor.d.ts +18 -0
  129. package/dist/types/core/editors/SelectEditor.d.ts +29 -0
  130. package/dist/types/core/export/ChannelRegistry.d.ts +18 -0
  131. package/dist/types/core/export/ExportManifest.d.ts +13 -0
  132. package/dist/types/core/export/GridArtifactSource.d.ts +62 -0
  133. package/dist/types/core/export/Provenance.d.ts +34 -0
  134. package/dist/types/core/export/StreamPump.d.ts +28 -0
  135. package/dist/types/core/export/channels/CsvChannel.d.ts +20 -0
  136. package/dist/types/core/export/channels/JsonChannel.d.ts +18 -0
  137. package/dist/types/core/export/channels/XlsxChannel.d.ts +53 -0
  138. package/dist/types/core/export/channels/XmlChannel.d.ts +21 -0
  139. package/dist/types/core/export/channels/capabilities.d.ts +13 -0
  140. package/dist/types/core/export/index.d.ts +24 -0
  141. package/dist/types/core/export/print/OutputChannelAdapter.d.ts +61 -0
  142. package/dist/types/core/export/print/Paginator.d.ts +48 -0
  143. package/dist/types/core/export/print/PrintRenderTarget.d.ts +36 -0
  144. package/dist/types/core/export/sinks.d.ts +40 -0
  145. package/dist/types/core/export/types.d.ts +211 -0
  146. package/dist/types/core/extension/DeprecationManager.d.ts +42 -0
  147. package/dist/types/core/extension/IExtension.d.ts +90 -0
  148. package/dist/types/core/extension/Registry.d.ts +142 -0
  149. package/dist/types/core/extension/SlotRegistry.d.ts +46 -0
  150. package/dist/types/core/extension/adapters.d.ts +44 -0
  151. package/dist/types/core/extension/conformance.d.ts +47 -0
  152. package/dist/types/core/extension/index.d.ts +16 -0
  153. package/dist/types/core/extension/registries.d.ts +31 -0
  154. package/dist/types/core/extension/reserved.d.ts +10 -0
  155. package/dist/types/core/format/DisplayFormatter.d.ts +47 -0
  156. package/dist/types/core/format/FormatCache.d.ts +20 -0
  157. package/dist/types/core/format/FormatterRegistry.d.ts +22 -0
  158. package/dist/types/core/format/grammar/AstRenderer.d.ts +10 -0
  159. package/dist/types/core/format/grammar/FormatCompiler.d.ts +16 -0
  160. package/dist/types/core/format/index.d.ts +55 -0
  161. package/dist/types/core/format/pipeline/DomainTypeResolver.d.ts +8 -0
  162. package/dist/types/core/format/pipeline/LocaleFormat.d.ts +11 -0
  163. package/dist/types/core/format/pipeline/ValueInterpreter.d.ts +8 -0
  164. package/dist/types/core/format/policy/MaskPolicy.d.ts +8 -0
  165. package/dist/types/core/format/policy/NegativePolicy.d.ts +12 -0
  166. package/dist/types/core/format/policy/NullPolicy.d.ts +10 -0
  167. package/dist/types/core/format/policy/TruncatePolicy.d.ts +11 -0
  168. package/dist/types/core/format/types.d.ts +292 -0
  169. package/dist/types/core/formula/CalcCacheStore.d.ts +89 -0
  170. package/dist/types/core/formula/CalcProvenance.d.ts +44 -0
  171. package/dist/types/core/formula/CalcService.d.ts +137 -0
  172. package/dist/types/core/formula/CyclePathReporter.d.ts +28 -0
  173. package/dist/types/core/formula/FormulaEvaluator.d.ts +35 -1
  174. package/dist/types/core/formula/FormulaGraph.d.ts +84 -7
  175. package/dist/types/core/formula/FormulaParser.d.ts +9 -0
  176. package/dist/types/core/formula/FormulaStore.d.ts +63 -1
  177. package/dist/types/core/formula/FunctionRegistry.d.ts +138 -0
  178. package/dist/types/core/formula/Generation.d.ts +86 -0
  179. package/dist/types/core/formula/RecalcCoordinator.d.ts +151 -9
  180. package/dist/types/core/formula/ReferenceRewriter.d.ts +81 -0
  181. package/dist/types/core/formula/functions/essential.d.ts +3 -0
  182. package/dist/types/core/formula/functions/extended/index.d.ts +10 -0
  183. package/dist/types/core/formula/normalizeRefs.d.ts +34 -3
  184. package/dist/types/core/formula/numericLiteral.d.ts +11 -1
  185. package/dist/types/core/formula/serializeFormula.d.ts +10 -1
  186. package/dist/types/core/host/CapabilityRegistry.d.ts +61 -0
  187. package/dist/types/core/host/GridHostDriver.d.ts +27 -0
  188. package/dist/types/core/host/GridHostPort.d.ts +37 -0
  189. package/dist/types/core/host/SliceOwnershipGuard.d.ts +27 -0
  190. package/dist/types/core/host/archCheck.d.ts +26 -0
  191. package/dist/types/core/host/index.d.ts +6 -0
  192. package/dist/types/core/host/reconcile.d.ts +22 -0
  193. package/dist/types/core/i18n/LocaleContext.d.ts +40 -0
  194. package/dist/types/core/i18n/types.d.ts +26 -1
  195. package/dist/types/core/icons/bootstrap-icons.d.ts +4 -2
  196. package/dist/types/core/quality/ContrastAuditor.d.ts +64 -0
  197. package/dist/types/core/quality/DeterminismKernel.d.ts +68 -0
  198. package/dist/types/core/quality/PerfBaseline.d.ts +23 -0
  199. package/dist/types/core/quality/PerfSpec.d.ts +95 -0
  200. package/dist/types/core/quality/RealBrowserGate.d.ts +69 -0
  201. package/dist/types/core/quality/RegressionJudge.d.ts +35 -0
  202. package/dist/types/core/quality/ReleaseGate.d.ts +94 -0
  203. package/dist/types/core/quality/VisualRegression.d.ts +74 -0
  204. package/dist/types/core/quality/hooks.d.ts +53 -0
  205. package/dist/types/core/quality/index.d.ts +20 -0
  206. package/dist/types/core/quality/pixelMetrics.d.ts +24 -0
  207. package/dist/types/core/range/ClipboardCodec.d.ts +46 -4
  208. package/dist/types/core/range/FillEngine.d.ts +69 -9
  209. package/dist/types/core/range/RangeModel.d.ts +100 -13
  210. package/dist/types/core/range/types.d.ts +27 -11
  211. package/dist/types/core/realtime/BackpressureScheduler.d.ts +0 -0
  212. package/dist/types/core/realtime/FreshnessClock.d.ts +34 -0
  213. package/dist/types/core/realtime/IRealtimeSource.d.ts +82 -0
  214. package/dist/types/core/realtime/LiveStateGuard.d.ts +23 -0
  215. package/dist/types/core/realtime/PollingSource.d.ts +42 -0
  216. package/dist/types/core/realtime/RealtimeController.d.ts +54 -0
  217. package/dist/types/core/realtime/RtAnnouncePolicy.d.ts +53 -0
  218. package/dist/types/core/realtime/RtApplyCommand.d.ts +29 -0
  219. package/dist/types/core/realtime/RtChartTargetTrigger.d.ts +26 -0
  220. package/dist/types/core/realtime/StreamingSource.d.ts +47 -0
  221. package/dist/types/core/realtime/backoff.d.ts +12 -0
  222. package/dist/types/core/realtime/index.d.ts +13 -0
  223. package/dist/types/core/realtime/ports.d.ts +80 -0
  224. package/dist/types/core/render/CellApplier.d.ts +18 -0
  225. package/dist/types/core/render/CellErrorBoundary.d.ts +65 -0
  226. package/dist/types/core/render/CellPipeline.d.ts +39 -0
  227. package/dist/types/core/render/CellRenderRequest.d.ts +209 -0
  228. package/dist/types/core/render/CellStageRegistry.d.ts +53 -0
  229. package/dist/types/core/render/OverlayCompositor.d.ts +38 -0
  230. package/dist/types/core/render/RenderBudget.d.ts +67 -0
  231. package/dist/types/core/render/contrast.d.ts +33 -0
  232. package/dist/types/core/render/index.d.ts +35 -0
  233. package/dist/types/core/render/stages/BackgroundStage.d.ts +14 -0
  234. package/dist/types/core/render/stages/DecoratorStage.d.ts +12 -0
  235. package/dist/types/core/render/stages/OverlayStage.d.ts +12 -0
  236. package/dist/types/core/render/stages/ValueRendererStage.d.ts +15 -0
  237. package/dist/types/core/render/stages/index.d.ts +14 -0
  238. package/dist/types/core/state/AutosaveController.d.ts +63 -0
  239. package/dist/types/core/state/IStatePersistence.d.ts +59 -0
  240. package/dist/types/core/state/MultiTabGuard.d.ts +33 -0
  241. package/dist/types/core/state/SchemaMigrator.d.ts +33 -0
  242. package/dist/types/core/state/SemVerPolicy.d.ts +39 -0
  243. package/dist/types/core/state/StateCodec.d.ts +75 -0
  244. package/dist/types/core/state/index.d.ts +6 -0
  245. package/dist/types/core/types.d.ts +17 -0
  246. package/dist/types/react/OpenGrid.d.ts +54 -0
  247. package/dist/types/react/index.d.ts +5 -0
  248. package/dist/types/realtime/index.d.ts +1 -0
  249. package/dist/types/vue/index.d.ts +5 -0
  250. package/dist/types/vue/types.d.ts +35 -0
  251. package/package.json +112 -111
@@ -1,49 +1,90 @@
1
1
  import { CellRange } from '../types.js';
2
2
  import { ChartAggregate, ChartDataModel, ChartSeriesSpec, ChartSource } from './types.js';
3
3
  import { ChartNumberFormat } from './a11y.js';
4
- /** ColumnLayout.visibleLeaves 의 최소 투영(field/header/type 만 필요, C0.4). */
4
+ /**
5
+ * ColumnLayout.visibleLeaves 의 최소 투영(field/header/type 만 필요, C0.4).
6
+ * / Minimal projection of ColumnLayout.visibleLeaves (only field/header/type are needed, C0.4).
7
+ */
5
8
  export interface ChartColumnRef {
9
+ /** 컬럼 field 키. / Column field key. */
6
10
  field: string;
11
+ /** 컬럼 헤더 라벨(시리즈 이름 폴백). / Column header label (series-name fallback). */
7
12
  header?: string | undefined;
13
+ /** 컬럼 데이터 타입(수치 판별 힌트). / Column data type (numeric-detection hint). */
8
14
  type?: string | undefined;
9
15
  }
16
+ /**
17
+ * 추출기가 그리드 상태에 접근하는 주입 함수 묶음. 실 그리드 없이도(단위테스트) 채울 수 있다.
18
+ * / Injected accessor bundle through which the extractor reads grid state. Can be supplied
19
+ * without a real grid (unit tests).
20
+ */
10
21
  export interface ChartExtractDeps {
11
- /** getData() 전체(display 순서) — kind='all'|'columns' */
22
+ /** getData() 전체(display 순서) — kind='all'|'columns'. / Full getData() rows (display order) — kind='all'|'columns'. */
12
23
  getAllRows(): Array<Record<string, any>>;
13
- /** getSelections() — kind='selection' */
24
+ /** getSelections() — kind='selection'. / getSelections() rows — kind='selection'. */
14
25
  getSelectedRows(): Array<Record<string, any>>;
15
- /** getChecked() 의 row 부분 — kind='checked' */
26
+ /** getChecked() 의 row 부분 — kind='checked'. / The row part of getChecked() — kind='checked'. */
16
27
  getCheckedRows(): Array<Record<string, any>>;
17
- /** ColumnLayout.visibleLeaves 투영(숨김 제외, C0.4) */
28
+ /** ColumnLayout.visibleLeaves 투영(숨김 제외, C0.4). / Projection of ColumnLayout.visibleLeaves (hidden excluded, C0.4). */
18
29
  getVisibleColumns(): ChartColumnRef[];
19
30
  /**
20
31
  * kind='range' 전용: 스냅샷/현재 range 에 대응하는 행 배열(FlatRowModel 로 이미
21
32
  * pseudo-row 를 제외한 상태, C0.3). 부재 시 range 소스는 selection 으로 강등한다(§7).
33
+ * / kind='range' only: rows matching the snapshot/current range (already pseudo-row-filtered
34
+ * via FlatRowModel, C0.3). When absent, the range source is downgraded to selection (§7).
22
35
  */
23
36
  getRangeRows?: ((range: CellRange) => Array<Record<string, any>>) | undefined;
24
- /** kind='range' 전용: range.startCol..endCol 에 대응하는 visibleLeaves 서브셋(C0.4). */
37
+ /**
38
+ * kind='range' 전용: range.startCol..endCol 에 대응하는 visibleLeaves 서브셋(C0.4).
39
+ * / kind='range' only: the visibleLeaves subset matching range.startCol..endCol (C0.4).
40
+ */
25
41
  getRangeColumns?: ((range: CellRange) => ChartColumnRef[]) | undefined;
26
- /** range 생략 시 초기값 취득(C4). 없거나 null 이면 selection 으로 강등(§7). */
42
+ /**
43
+ * range 생략 시 초기값 취득(C4). 없거나 null 이면 selection 으로 강등(§7).
44
+ * / Obtain the initial range when omitted (C4). Absent or null downgrades to selection (§7).
45
+ */
27
46
  getActiveRange?: (() => CellRange | null) | undefined;
28
47
  }
48
+ /**
49
+ * 추출 동작 설정(override·집계·포맷). / Extraction behavior config (overrides, aggregation, format).
50
+ */
29
51
  export interface ChartExtractConfig {
30
- /** 축 카테고리 컬럼 override(FR-2). 미지정 시 §2.2 자동 추론. */
52
+ /** 축 카테고리 컬럼 override(FR-2). 미지정 시 §2.2 자동 추론. / Category column override (FR-2). Auto-inferred (§2.2) if unset. */
31
53
  category?: string | undefined;
32
- /** 시리즈 컬럼 override(FR-2). 'columns' 소스는 필수(source.series 로도 지정 가능). */
54
+ /** 시리즈 컬럼 override(FR-2). 'columns' 소스는 필수(source.series 로도 지정 가능). / Series column override (FR-2). Required for the 'columns' source (source.series also works). */
33
55
  series?: Array<string | ChartSeriesSpec> | undefined;
34
- /** 동일 category 중복 시 축약(FR-3). 미지정 시 중복 category 를 그대로 유지(비집계). */
56
+ /** 동일 category 중복 시 축약(FR-3). 미지정 시 중복 category 를 그대로 유지(비집계). / Aggregate duplicate categories (FR-3). Unset keeps duplicates as-is (no aggregation). */
35
57
  aggregate?: ChartAggregate | undefined;
58
+ /** a11y 캡션/제목. / a11y caption/title. */
36
59
  title?: string | undefined;
60
+ /** 축·툴팁 값 포맷터. / Axis/tooltip value formatter. */
37
61
  numberFormat?: ChartNumberFormat | undefined;
38
62
  }
39
- /** 소스 강등 없이 실제로 사용된 소스 종류(§7 fallback 반영, 배지 판단에 쓰라고 반환). */
63
+ /**
64
+ * 추출 결과 — 모델 + 실제로 사용된 소스 반영(§7 fallback, 배지 판단용).
65
+ * / Extraction result — the model plus the source actually used (§7 fallback, for badge decisions).
66
+ */
40
67
  export interface ChartExtractResult {
68
+ /** 산출된 차트 데이터 모델. / The produced chart data model. */
41
69
  model: ChartDataModel;
42
- /** true 면 kind='range' 요청이 selection 으로 강등됐다(F1 부재/range 미해소, §7 HANMS-04). */
70
+ /** true 면 kind='range' 요청이 selection 으로 강등됐다(F1 부재/range 미해소, §7 HANMS-04). / true when a kind='range' request was downgraded to selection (F1 absent/range unresolved, §7). */
43
71
  rangeFallback: boolean;
44
72
  }
45
73
  /**
46
74
  * 소스(§2.1)로부터 `ChartDataModel`을 산출한다(FR-1: 4소스 → 동형 모델).
47
75
  * `meta.a11yTable`은 항상 채운다(§B 하드 게이트, "생성비용 0" 미러).
76
+ * / Produce a `ChartDataModel` from a source (§2.1) (FR-1: 4 sources → one isomorphic model).
77
+ * `meta.a11yTable` is always populated (§B hard gate, a "zero-cost" mirror).
78
+ *
79
+ * @param source - 데이터 소스(all/columns/selection/checked/range, §2.1) / Data source (all/columns/selection/checked/range, §2.1)
80
+ * @param deps - 그리드 상태 접근 주입 함수 묶음 / Injected grid-state accessor bundle
81
+ * @param config - 축/시리즈 override·집계·포맷(선택) / Axis/series override, aggregation, format (optional)
82
+ * @returns 모델 + range→selection 강등 여부 / The model plus whether range was downgraded to selection
83
+ * @example
84
+ * const { model, rangeFallback } = extractChartData(
85
+ * { kind: 'all' },
86
+ * { getAllRows: () => rows, getSelectedRows: () => [], getCheckedRows: () => [], getVisibleColumns: () => cols },
87
+ * { aggregate: 'sum' }
88
+ * );
48
89
  */
49
90
  export declare function extractChartData(source: ChartSource, deps: ChartExtractDeps, config?: ChartExtractConfig): ChartExtractResult;
@@ -1,10 +1,18 @@
1
1
  import { ChartDataModel, A11yTableModel } from './types.js';
2
+ /**
3
+ * 축/툴팁/범례 값 포맷터. 값과 문맥(축 종류·field)을 받아 표시 문자열을 반환한다.
4
+ * / Axis/tooltip/legend value formatter. Takes a value and context (axis kind, field) and
5
+ * returns the display string.
6
+ */
2
7
  export type ChartNumberFormat = (v: number, ctx: {
3
8
  axis: 'x' | 'y' | 'tooltip' | 'legend';
4
9
  field?: string;
5
10
  }) => string;
11
+ /** a11y 테이블 생성 옵션. / Options for building the a11y table. */
6
12
  export interface BuildA11yTableOptions {
13
+ /** 캡션 요약에 넣을 제목. / Title to embed in the caption summary. */
7
14
  title?: string | undefined;
15
+ /** 셀 값 포맷터(미지정 시 String()). / Cell value formatter (String() if unset). */
8
16
  numberFormat?: ChartNumberFormat | undefined;
9
17
  }
10
18
  /**
@@ -12,10 +20,24 @@ export interface BuildA11yTableOptions {
12
20
  * - colHeaders: ['category', ...series names]
13
21
  * - rows: [category, v1, v2, ...] (locale 포맷 문자열, 결측=빈 문자열)
14
22
  * - caption: 요약 — 카테고리 수·시리즈명 나열(스크린리더가 표 진입 전 듣는 개요).
23
+ * / Convert a `ChartDataModel` (categories/series part) into visually-hidden `<table>` mirror
24
+ * data (§B.1). colHeaders = ['category', ...series names]; rows = [category, v1, v2, …]
25
+ * (locale-formatted strings, missing = empty string); caption = a summary listing the category
26
+ * count and series names (the overview a screen reader hears before entering the table).
27
+ *
28
+ * @param model - categories/series 를 담은 모델 조각 / Model slice carrying categories/series
29
+ * @param opts - 제목·값 포맷터(선택) / Title and value formatter (optional)
30
+ * @returns 캡션·컬럼헤더·행으로 이뤄진 A11yTableModel / An A11yTableModel of caption, column headers, and rows
15
31
  */
16
32
  export declare function buildA11yTable(model: Pick<ChartDataModel, 'categories' | 'series'>, opts?: BuildA11yTableOptions): A11yTableModel;
17
33
  /**
18
34
  * `<canvas role="img" aria-label="...">` 에 쓸 요약 문자열(§B.1).
19
35
  * "{title}: {category}별 {series} — {요약}" 형태. 상세 값은 형제 `<table>`(aria-describedby)로.
36
+ * / The summary string for `<canvas role="img" aria-label="...">` (§B.1). Detailed values live
37
+ * in the sibling `<table>` (via aria-describedby).
38
+ *
39
+ * @param model - categories/series 를 담은 모델 조각 / Model slice carrying categories/series
40
+ * @param title - 차트 제목(미지정 시 기본 제목) / Chart title (default title if unset)
41
+ * @returns aria-label 문자열 / The aria-label string
20
42
  */
21
43
  export declare function chartAriaLabel(model: Pick<ChartDataModel, 'categories' | 'series'>, title?: string): string;
@@ -0,0 +1,53 @@
1
+ import { ChartDataModel, ChartRenderSpec } from './types.js';
2
+ import { ChartGeometry } from './geometry.js';
3
+ import { DrawPrim } from './scene.js';
4
+ import { RegisterOptions, RegisterResult } from '../extension/Registry.js';
5
+ /**
6
+ * 차트타입 렌더러 SPI — 순수. 공유 기하 → 자기 타입의 DrawPrim 기여(surface 미접촉, humble 유지).
7
+ * `buildChartScene` 이 타입별로 이 renderer 를 호출해 prims 를 조립한다(Strategy).
8
+ * / Chart-type renderer SPI — pure. Shared geometry → this type's DrawPrim contribution (never
9
+ * touches a surface). buildChartScene calls it per type to assemble prims (Strategy).
10
+ */
11
+ export interface IChartRenderer {
12
+ /** 타입 키('bar'|'line'|…|커스텀). / Type key. */
13
+ readonly type: string;
14
+ /** 기하 힌트(정직성 §9.3 불변식). / Geometry hints (honesty invariants). */
15
+ readonly geometryHints?: {
16
+ forceZeroBaseline?: boolean;
17
+ radialLinearOnly?: boolean;
18
+ };
19
+ /** 공유 기하+색스냅샷 → 이 타입의 원시 드로우명령. DOM/canvas 미참조(불변식1). / Shared geometry → prims. */
20
+ toPrims(model: ChartDataModel, spec: ChartRenderSpec, geo: ChartGeometry): readonly DrawPrim[];
21
+ }
22
+ /** SPI 이름·버전(peer 검증). / SPI name/version (peer verification). */
23
+ export declare const CHART_TYPE_SPI: {
24
+ readonly name: "IChartRenderer";
25
+ readonly version: "1";
26
+ };
27
+ /**
28
+ * 차트타입 레지스트리(§2.9) — DD-10 IRegistry 동형. resolve=lazy get, 미지 타입=null(→ unsupportedType
29
+ * 배지, 조용한 폴백 금지 불변식4). 빌트인도 override 로 교체 가능(OCP).
30
+ * / Chart-type registry (§2.9) — homomorphic to DD-10 IRegistry. resolve = lazy get; unknown type =
31
+ * null (→ unsupportedType badge, no silent fallback). Built-ins are override-replaceable (OCP).
32
+ */
33
+ export declare class ChartTypeRegistry {
34
+ private _reg;
35
+ constructor();
36
+ /**
37
+ * 렌더러 등록(정책 위임). / Register a renderer (policy delegated).
38
+ * @param r - 차트타입 렌더러 / Chart-type renderer
39
+ * @param opts - 등록 정책 메타(origin·override 등) / Registration policy meta
40
+ * @returns 등록 결과(never-throw) / Registration result (never-throw)
41
+ */
42
+ register(r: IChartRenderer, opts?: RegisterOptions): RegisterResult;
43
+ /**
44
+ * 타입 → 렌더러(미등록 null → unsupportedType 배지). / Type → renderer (null when unregistered).
45
+ * @param type - 차트타입 키 / Chart-type key
46
+ * @returns 렌더러 또는 null / The renderer or null
47
+ */
48
+ resolve(type: string): IChartRenderer | null;
49
+ /** 등록 키 목록. / Registered keys. */
50
+ list(): string[];
51
+ /** 존재 여부. / Whether a type is registered. */
52
+ has(type: string): boolean;
53
+ }
@@ -0,0 +1,36 @@
1
+ import { ChartDataModel, ChartType } from './types.js';
2
+ /** 다운샘플 정직성 보고(§2.7). / Downsample honesty report (§2.7). */
3
+ export interface DownsampleReport {
4
+ /** 원본 포인트 수(배지 N). / Original point count (badge N). */
5
+ readonly from: number;
6
+ /** 축약 포인트 수(배지 M). / Reduced point count (badge M). */
7
+ readonly to: number;
8
+ /** 전역 min/max 정확 보존(100% 게이트). / Exact global min/max preserved. */
9
+ readonly extremaPreserved: boolean;
10
+ /** series 별 극값 보존. / Per-series extrema preservation. */
11
+ readonly perSeriesExtrema: ReadonlyArray<{
12
+ minKept: boolean;
13
+ maxKept: boolean;
14
+ }>;
15
+ /** 로컬 특징(피크/급증) 검출율(≥0.95 게이트). / Local-feature detection rate. */
16
+ readonly featureDetectRate: number;
17
+ /** 표시 편차(≤1px 게이트). / Max display deviation in px. */
18
+ readonly maxDisplayDeviationPx: number;
19
+ }
20
+ /**
21
+ * 원본↔축약 비교로 정직성 보고를 계량한다(line/area 대상). bar/pie(버킷 집계)는 값이 변형되므로
22
+ * 극값 계량이 무의미 → from/to 만 채우고 featureDetectRate=1(집계는 다른 정직성 축, 배지가 고지).
23
+ * / Quantify the honesty report by comparing original↔reduced (for line/area). For bar/pie (bucket
24
+ * aggregation) values change, so extrema metrics are moot → fill from/to only, featureDetectRate=1
25
+ * (aggregation is a different honesty axis, disclosed by the badge).
26
+ *
27
+ * @param original - 원본 모델 / Original model
28
+ * @param reduced - 축약 모델 / Reduced model
29
+ * @param type - 차트 타입 / Chart type
30
+ * @param size - 표시 편차 계량용 크기(선택, 기본 480×300) / Size for display-deviation metric (default 480×300)
31
+ * @returns 다운샘플 보고 / The downsample report
32
+ */
33
+ export declare function analyzeDownsample(original: ChartDataModel, reduced: ChartDataModel, type: ChartType, size?: {
34
+ width: number;
35
+ height: number;
36
+ }): DownsampleReport;
@@ -3,23 +3,48 @@ import { ChartNumberFormat } from './a11y.js';
3
3
  /**
4
4
  * LTTB 코어 — x(=category index 0..n-1)·y(대표값) 에서 threshold 개 인덱스를 고른다.
5
5
  * 항상 첫/마지막을 포함한다. threshold>=n 이면 전 인덱스 반환.
6
+ * / LTTB core — pick `threshold` indices from x (= category index 0..n-1) and y (representative
7
+ * values). Always includes the first and last; returns all indices when threshold ≥ n.
8
+ *
9
+ * @param y - 대표값 배열(null 은 0 취급) / Representative-value array (null treated as 0)
10
+ * @param threshold - 목표 선택 개수 / Target number of picks
11
+ * @returns 오름차순 선택 인덱스 배열 / Ascending array of selected indices
6
12
  */
7
13
  export declare function lttbIndices(y: Array<number | null>, threshold: number): number[];
14
+ /** 다운샘플 결과. / Downsample result. */
8
15
  export interface DownsampleResult {
16
+ /** 축약된(또는 원본) 차트 데이터 모델. / The downsampled (or original) chart data model. */
9
17
  model: ChartDataModel;
10
- /** true 면 축약이 일어났다(배지 §C). */
18
+ /** true 면 축약이 일어났다(배지 §C). / true when downsampling occurred (badge §C). */
11
19
  sampled: boolean;
12
20
  }
21
+ /** 다운샘플 옵션(a11y 테이블 재생성용). / Downsample options (for a11y-table regeneration). */
13
22
  export interface DownsampleOptions {
23
+ /** a11y 캡션 제목. / a11y caption title. */
14
24
  title?: string | undefined;
25
+ /** 셀 값 포맷터. / Cell value formatter. */
15
26
  numberFormat?: ChartNumberFormat | undefined;
16
27
  }
17
28
  /**
18
29
  * `ChartDataModel`을 maxPoints 이하로 축약한다(§8.2). categories/series 를 함께 줄여
19
30
  * 정합을 유지하고, meta.sampled/sampledFrom/sampledTo 를 채운다(배지 §C). a11yTable 은
20
31
  * 축약된 데이터로 재생성해 모델 자기정합을 유지한다(§B.4: 셀 수 == categories×(series+1)).
32
+ * / Downsample a `ChartDataModel` to at most maxPoints (§8.2). categories and series are reduced
33
+ * together to stay consistent, and meta.sampled/sampledFrom/sampledTo are filled (badge §C). The
34
+ * a11yTable is regenerated from the reduced data to keep the model self-consistent
35
+ * (§B.4: cell count == categories×(series+1)).
21
36
  *
22
37
  * - line/area: 공유 인덱스 LTTB + 각 series 엔벨로프(argmin/argmax) 강제 포함 → 극값 정확 보존.
23
38
  * - 그 외(bar): 인접 category 를 균등 버킷으로 묶어 대표(첫 category 라벨) + 값 합산.
39
+ * / - line/area: shared-index LTTB plus each series's forced envelope (argmin/argmax) → exact
40
+ * extrema preservation.
41
+ * - otherwise (bar): group adjacent categories into even buckets with a representative (first
42
+ * category label) and summed values.
43
+ *
44
+ * @param model - 축약 대상 모델 / Model to downsample
45
+ * @param maxPoints - 목표 상한 포인트 수 / Target maximum point count
46
+ * @param type - 차트 종류(line/area vs 그 외 분기) / Chart type (line/area vs otherwise branch)
47
+ * @param opts - a11y 재생성용 제목·포맷터(선택) / Title/formatter for a11y regeneration (optional)
48
+ * @returns 축약 모델 + 축약 여부 / The (possibly) downsampled model plus whether it was sampled
24
49
  */
25
50
  export declare function downsampleModel(model: ChartDataModel, maxPoints: number, type: ChartType, opts?: DownsampleOptions): DownsampleResult;
@@ -0,0 +1,52 @@
1
+ import { ChartAdapter } from '../types.js';
2
+ /** 외부 엔진 스펙. / External engine spec. */
3
+ export interface ExternalEngineSpec {
4
+ /** 엔진 id. / Engine id. */
5
+ id: 'chartjs' | 'echarts' | string;
6
+ /** CDN/self-host URL. / CDN or self-host URL. */
7
+ url: string;
8
+ /** integrity 해시(공급망 게이트) — 없으면 로드 거부. / integrity hash; missing → load refused. */
9
+ sri: string;
10
+ /** window 전역명(미로드 감지). / window global name (not-loaded detection). */
11
+ globalName: string;
12
+ }
13
+ /** 엔진 로더(host 주입) — 스펙 → 어댑터(실패 null). / Engine loader (host-injected). */
14
+ export type EngineLoader = (spec: ExternalEngineSpec) => Promise<ChartAdapter | null>;
15
+ /** SRI 해시 형식 검증(sha256/384/512-base64). / Validate SRI hash format. */
16
+ export declare function isValidSri(sri: string): boolean;
17
+ /** 엔진 해소 결과(조용한 폴백 금지 — 사유를 값으로). / Engine resolution result (reason as value). */
18
+ export interface EngineResolveResult {
19
+ /** 해소된 어댑터(실패 시 null → builtin 폴백). / Resolved adapter (null → builtin fallback). */
20
+ readonly adapter: ChartAdapter | null;
21
+ /** 폴백 사유(engineFallback 배지 근거). / Fallback reason (basis for engineFallback badge). */
22
+ readonly reason?: 'not-registered' | 'invalid-sri' | 'load-failed';
23
+ }
24
+ /**
25
+ * 외부 엔진 레지스트리(§2.8) — DD-10 IRegistry 동형. register 는 SRI 형식을 게이트하고, resolve 는
26
+ * 주입 loader 로 lazy 로드해 실패를 값으로 고지한다(조용한 폴백 금지).
27
+ * / External-engine registry — homomorphic to DD-10 IRegistry. register gates SRI format; resolve
28
+ * lazy-loads via the injected loader and reports failure as a value (no silent fallback).
29
+ */
30
+ export declare class ChartEngineRegistry {
31
+ private _reg;
32
+ private _loader;
33
+ /** @param loader - host 주입 스크립트 로더(없으면 항상 load-failed → builtin) / Host-injected loader */
34
+ constructor(loader?: EngineLoader);
35
+ /**
36
+ * 엔진 스펙 등록 — SRI 형식 불량은 거부(공급망 게이트). / Register an engine spec; bad SRI is refused.
37
+ * @param spec - 외부 엔진 스펙 / External engine spec
38
+ * @returns 등록 성공 여부 / Whether registration succeeded
39
+ */
40
+ register(spec: ExternalEngineSpec): boolean;
41
+ /**
42
+ * lazy 로드 시도 — 성공 시 어댑터, 실패/미로드/미등록 시 null + 사유(→ builtin 폴백 + 배지).
43
+ * / Lazy load — adapter on success; null + reason on failure/not-loaded/unregistered.
44
+ * @param id - 엔진 id / Engine id
45
+ * @returns 어댑터 또는 null + 폴백 사유 / Adapter or null + fallback reason
46
+ */
47
+ resolve(id: string): Promise<EngineResolveResult>;
48
+ /** 등록 키 목록. / Registered keys. */
49
+ list(): string[];
50
+ /** 존재 여부. / Whether an engine is registered. */
51
+ has(id: string): boolean;
52
+ }
@@ -0,0 +1,96 @@
1
+ import { ChartDataModel, ChartRenderSpec } from './types.js';
2
+ import { NiceScale } from './scales.js';
3
+ import { PointGeom } from './hittest.js';
4
+ /** 플롯 영역(축 안쪽 그리기 사각형). / Plot rectangle (inside axes). */
5
+ export interface PlotRect {
6
+ readonly x: number;
7
+ readonly y: number;
8
+ readonly w: number;
9
+ readonly h: number;
10
+ }
11
+ /** 축 틱 배치(값 + 픽셀 좌표 + 라벨). / Axis tick placement (value + pixel coord + label). */
12
+ export interface AxisTick {
13
+ readonly value: number;
14
+ readonly label: string;
15
+ readonly px: number;
16
+ }
17
+ /** x축 카테고리 라벨 배치. / x-axis category label placement. */
18
+ export interface XLabel {
19
+ readonly index: number;
20
+ readonly label: string;
21
+ readonly px: number;
22
+ }
23
+ /** 범례 항목 배치 박스(hit·포커스 대상, 세 타깃 공유). / Legend item box (shared hit/focus target). */
24
+ export interface LegendBox {
25
+ readonly seriesIndex: number;
26
+ readonly label: string;
27
+ readonly x: number;
28
+ readonly y: number;
29
+ readonly w: number;
30
+ readonly h: number;
31
+ }
32
+ /**
33
+ * pie/doughnut 슬라이스 기하 — 값→각도 **선형 사상만**(반지름 인코딩 금지, §9.3.2 정직성).
34
+ * / pie/doughnut slice geometry — value → angle **linear mapping only** (radius encoding banned).
35
+ */
36
+ export interface PieSliceGeom {
37
+ readonly index: number;
38
+ /** 시작 각(라디안, 12시=-PI/2 기준 시계방향). / Start angle (rad, 12 o'clock = -PI/2, clockwise). */
39
+ readonly a0: number;
40
+ /** 끝 각. / End angle. */
41
+ readonly a1: number;
42
+ /** 원본 값(음수 절댓값 처리 전이 아니라, 각도 산정에 쓰인 절댓값). / Absolute value used for angle. */
43
+ readonly value: number;
44
+ /** 라벨 배치용 중앙 반경 지점. / Centroid point for label placement. */
45
+ readonly cx: number;
46
+ readonly cy: number;
47
+ }
48
+ /**
49
+ * 차트 하나의 완전한 기하 — 세 타깃이 공유하는 좌표 진실원(§2.1).
50
+ * PointGeom(hittest.ts) 을 그대로 재사용해 hit-test 정합을 보장한다.
51
+ * / The complete geometry of one chart — the shared coordinate SSOT. Reuses PointGeom (hittest.ts)
52
+ * verbatim to keep hit-test coherent.
53
+ */
54
+ export interface ChartGeometry {
55
+ readonly plot: PlotRect;
56
+ readonly scale: NiceScale;
57
+ readonly points: readonly PointGeom[];
58
+ readonly yTicks: readonly AxisTick[];
59
+ readonly xLabels: readonly XLabel[];
60
+ readonly legend: readonly LegendBox[];
61
+ /** 0 기준선 픽셀 y(정직성 §9.3.1 — 막대 축 절단 방지). / Baseline (value 0) pixel y. */
62
+ readonly baselineY: number;
63
+ /** pie/doughnut 슬라이스(해당 타입에서만). / pie/doughnut slices (only for those types). */
64
+ readonly pie?: readonly PieSliceGeom[];
65
+ }
66
+ /** 기본 플롯 여백(현 CanvasAdapter 상수와 동일 — 기하 파리티). / Default plot padding (matches CanvasAdapter). */
67
+ export declare const PLOT_PAD: {
68
+ readonly top: 26;
69
+ readonly right: 14;
70
+ readonly bottom: 34;
71
+ readonly left: 52;
72
+ };
73
+ /** line/area 마커 반경(현 CanvasAdapter 와 동일). / line/area marker radius (matches CanvasAdapter). */
74
+ export declare const MARKER_R = 3.5;
75
+ /** 라벨 폭 근사 계수(em 당 문자폭, measureText 금지). / Label-width em coefficient (no measureText). */
76
+ export declare const EM_WIDTH_FACTOR = 0.6;
77
+ /**
78
+ * 결정론적 텍스트 폭 근사(문자수×fontSize×em 계수). measureText 를 금지해 세 타깃 파리티를 지킨다.
79
+ * / Deterministic text-width approximation (char-count × fontSize × em). Bans measureText to keep
80
+ * the three targets in parity.
81
+ */
82
+ export declare function estimateTextWidth(s: string, fontSize: number): number;
83
+ /**
84
+ * 순수: (모델·스펙·크기·숨김집합) → 완전 기하. canvas/svg/server 공통 진입점(§2.1).
85
+ * / Pure: (model, spec, size, hidden) → complete geometry. The common entry for canvas/svg/server.
86
+ *
87
+ * @param model - 차트 데이터 모델 / Chart data model
88
+ * @param spec - 렌더 스펙(타입·테마·포맷) / Render spec (type, theme, format)
89
+ * @param size - 렌더 크기(CSS px) / Render size (CSS px)
90
+ * @param hidden - 숨긴 series 인덱스 집합(범례 토글) / Hidden series indices (legend toggle)
91
+ * @returns 완전 기하(세 타깃 공유) / Complete geometry (shared by three targets)
92
+ */
93
+ export declare function computeChartGeometry(model: ChartDataModel, spec: ChartRenderSpec, size: {
94
+ width: number;
95
+ height: number;
96
+ }, hidden?: ReadonlySet<number>): ChartGeometry;
@@ -1,20 +1,38 @@
1
1
  import { ChartType } from './types.js';
2
- /** 렌더된 데이터포인트 하나의 기하. bar=사각형(x,y,w,h), line/marker=중심(cx,cy). */
2
+ /**
3
+ * 렌더된 데이터포인트 하나의 기하. bar=사각형(x,y,w,h), line/marker=중심(cx,cy).
4
+ * / Geometry of one rendered data point. bar = rectangle (x,y,w,h); line/marker = center (cx,cy).
5
+ */
3
6
  export interface PointGeom {
7
+ /** 시리즈 인덱스. / Series index. */
4
8
  seriesIndex: number;
9
+ /** 카테고리 인덱스. / Category index. */
5
10
  categoryIndex: number;
6
- /** 사각형 좌상단(bar). line 은 마커 bbox 좌상단으로도 채울 수 있다. */
11
+ /** 사각형 좌상단 x(bar). line 은 마커 bbox 좌상단으로도 채울 수 있다. / Rect top-left x (bar); line may fill it with the marker bbox top-left. */
7
12
  x: number;
13
+ /** 사각형 좌상단 y. / Rect top-left y. */
8
14
  y: number;
15
+ /** 사각형 너비. / Rect width. */
9
16
  w: number;
17
+ /** 사각형 높이. / Rect height. */
10
18
  h: number;
11
- /** 중심 좌표(line 마커 최근접용, bar 도 중심 계산해 채운다). */
19
+ /** 중심 x(line 마커 최근접용, bar 도 중심 계산해 채운다). / Center x (for line-marker nearest; bar also fills its center). */
12
20
  cx: number;
21
+ /** 중심 y. / Center y. */
13
22
  cy: number;
14
23
  }
15
24
  /**
16
25
  * 포인터 좌표(px,py)에 해당하는 데이터포인트 기하를 찾는다(§8.3).
17
26
  * - bar/bar-*: 사각형 contains(미스면 null → 툴팁 숨김).
18
27
  * - line/area: 최근접 x → 최근접 y(항상 하나 반환, 미스 개념 없음).
28
+ * / Find the data-point geometry at pointer coords (px,py) (§8.3).
29
+ * - bar/bar-*: rectangle contains (null on miss → tooltip hidden).
30
+ * - line/area: nearest x → nearest y (always returns one; no "miss" concept).
31
+ *
32
+ * @param geoms - 렌더된 포인트 기하 배열 / Array of rendered point geometry
33
+ * @param px - 포인터 x(geom 좌표계) / Pointer x (geom coordinate space)
34
+ * @param py - 포인터 y(geom 좌표계) / Pointer y (geom coordinate space)
35
+ * @param type - 차트 종류(bar vs line/area 분기) / Chart type (bar vs line/area branch)
36
+ * @returns 히트된 PointGeom, 없으면 null / The hit PointGeom, or null if none
19
37
  */
20
38
  export declare function hitTest(geoms: readonly PointGeom[], px: number, py: number, type: ChartType): PointGeom | null;
@@ -1,43 +1,117 @@
1
1
  import { ChartSeries } from './types.js';
2
- /** Okabe-Ito 8색(색약 안전 세트) — 배치 순서는 인접 대비≥3:1이 되도록 §D에 맞춰 조정. */
2
+ /**
3
+ * Okabe-Ito 8색(색약 안전 세트) — 배치 순서는 인접 대비를 키우도록 §D에 맞춰 조정.
4
+ * / Okabe-Ito 8-color colorblind-safe set — ordering tuned per §D to raise adjacent contrast.
5
+ */
3
6
  export declare const OKABE_ITO: readonly string[];
4
- /** 색 외 구분(§D): series 인덱스 순환 배정. bar=텍스처, line=대시+마커에 대응. */
7
+ /**
8
+ * 색 외 구분(§D): series 인덱스 순환 배정. bar=텍스처, line=대시+마커에 대응.
9
+ * / Redundant (non-color) encoding (§D): assigned by series index cycling. Maps to texture for
10
+ * bars, dash + marker for lines.
11
+ */
5
12
  export declare const PATTERN_CYCLE: ReadonlyArray<NonNullable<ChartSeries['pattern']>>;
13
+ /** RGB 색(각 채널 0..255). / An RGB color (each channel 0..255). */
6
14
  export interface Rgb {
15
+ /** 빨강 0..255. / Red 0..255. */
7
16
  r: number;
17
+ /** 초록 0..255. / Green 0..255. */
8
18
  g: number;
19
+ /** 파랑 0..255. / Blue 0..255. */
9
20
  b: number;
10
21
  }
11
- /** '#rgb'/'#rrggbb'/'rgb(a)()' → RGB(0-255). 실패 시 null. */
22
+ /**
23
+ * '#rgb'/'#rrggbb'/'rgb(a)()' → RGB(0-255). 실패 시 null.
24
+ * / Parse '#rgb'/'#rrggbb'/'rgb(a)()' → RGB (0-255). null on failure.
25
+ *
26
+ * @param input - 색 문자열 / Color string
27
+ * @returns RGB 객체, 파싱 실패 시 null / An RGB object, or null on parse failure
28
+ */
12
29
  export declare function parseColor(input: string): Rgb | null;
13
- /** 'rgba(r, g, b, 1)' 정규화 문자열 — UR-2 theme_bind 비교용(§1). */
30
+ /**
31
+ * 'rgba(r, g, b, 1)' 정규화 문자열 — 테마 바인딩 비교용(§1).
32
+ * / Normalized 'rgba(r, g, b, 1)' string — for theme-binding comparison (§1).
33
+ *
34
+ * @param input - 색 문자열 / Color string
35
+ * @returns 정규화 문자열, 실패 시 null / Normalized string, or null on failure
36
+ */
14
37
  export declare function normalizeColor(input: string): string | null;
15
- /** WCAG relative luminance (0..1). */
38
+ /** WCAG relative luminance (0..1). / WCAG relative luminance (0..1). */
16
39
  export declare function relativeLuminance(c: Rgb): number;
17
- /** WCAG 대비비 (1..21). 파싱 실패 색은 1로 취급. */
40
+ /**
41
+ * WCAG 대비비 (1..21). 파싱 실패 색은 1로 취급.
42
+ * / WCAG contrast ratio (1..21). Unparseable colors are treated as 1.
43
+ *
44
+ * @param a - 색 문자열 A / Color string A
45
+ * @param b - 색 문자열 B / Color string B
46
+ * @returns 대비비 1..21 / Contrast ratio 1..21
47
+ */
18
48
  export declare function contrastRatio(a: string, b: string): number;
49
+ /** 이색각(색약) 종류. / Dichromacy (colorblindness) kind. */
19
50
  export type Dichromacy = 'deuteranopia' | 'protanopia';
20
- /** 색약 변환 시뮬레이션 — RGB in/out(0-255). */
51
+ /**
52
+ * 색약 변환 시뮬레이션 — RGB in/out(0-255).
53
+ * / Simulate a dichromatic color transform — RGB in/out (0-255).
54
+ *
55
+ * @param c - 원본 RGB / Source RGB
56
+ * @param kind - 색약 종류 / Dichromacy kind
57
+ * @returns 시뮬레이션된 RGB / The simulated RGB
58
+ */
21
59
  export declare function simulateDichromacy(c: Rgb, kind: Dichromacy): Rgb;
22
- /** 단순 유클리드 RGB 거리(ΔE 근사, 0..441). palette.spec 임계 비교용. */
60
+ /**
61
+ * 단순 유클리드 RGB 거리(ΔE 근사, 0..441). 팔레트 임계 비교용.
62
+ * / Simple Euclidean RGB distance (ΔE approximation, 0..441). For palette threshold comparisons.
63
+ *
64
+ * @param a - RGB A / RGB A
65
+ * @param b - RGB B / RGB B
66
+ * @returns 거리 0..441 / Distance 0..441
67
+ */
23
68
  export declare function colorDistance(a: Rgb, b: Rgb): number;
24
69
  /**
25
70
  * 인접 대비를 **최대화**하도록 팔레트를 그리디 재배치한다(§D "미달 시 팔레트 재배치").
26
71
  * 첫 색에서 시작해 매번 직전 색과 대비가 가장 큰 색을 이어붙인다(O(n²), 결정론적).
72
+ * / Greedily reorder the palette to **maximize** adjacent contrast (§D "reorder when below
73
+ * target"). Starting from the first color, each step appends the color with the greatest
74
+ * contrast against the previous one (O(n²), deterministic).
27
75
  *
28
76
  * ⚠️ 정직한 한계(설계 갱신 필요): 8색 색약안전 팔레트는 **어떤 순열로도** 인접 luminance
29
77
  * 대비 ≥3:1 을 전부 만족할 수 없다(수학적 상한 ≈1.52, 브루트포스 확인). WCAG 3:1 은 본디
30
78
  * 전경-배경(텍스트/UI) 기준이지 인접 카테고리 기준이 아니다. 색약 구별의 실보증은 (1) 색약
31
- * 시뮬 ΔE 분리(§simulateDichromacy, 인접 최소 ≈78)와 (2) 색 외 중복 부호화(패턴/대시/마커,
32
- * PATTERN_CYCLE)에 있다. 본 함수는 대비를 "가능한 만큼" 키우는 best-effort 재배치다.
79
+ * 시뮬 ΔE 분리(인접 최소 ≈78)와 (2) 색 외 중복 부호화(패턴/대시/마커, PATTERN_CYCLE)에 있다.
80
+ * 본 함수는 대비를 "가능한 만큼" 키우는 best-effort 재배치다.
81
+ * / ⚠️ Honest limitation: the 8-color colorblind-safe palette cannot satisfy adjacent luminance
82
+ * contrast ≥ 3:1 for all pairs under **any** permutation (mathematical upper bound ≈ 1.52,
83
+ * brute-force confirmed). WCAG 3:1 is originally a foreground-background (text/UI) criterion, not
84
+ * an adjacent-category one. The real guarantee of colorblind distinguishability rests on (1) the
85
+ * dichromacy-simulated ΔE separation (adjacent minimum ≈ 78) and (2) redundant non-color encoding
86
+ * (pattern/dash/marker, PATTERN_CYCLE). This function is a best-effort reordering that raises
87
+ * contrast "as much as possible".
88
+ *
89
+ * @param colors - 재배치할 색 배열 / Colors to reorder
90
+ * @returns 인접 대비를 키운 새 순열(원순서보다 나빠지지 않음) / A new permutation with raised adjacent contrast (never worse than the original)
33
91
  */
34
92
  export declare function orderByAdjacentContrast(colors: readonly string[]): string[];
35
- /** 인접 색쌍의 최소 대비비(테스트/재배치 판정용). */
93
+ /**
94
+ * 인접 색쌍의 최소 대비비(테스트/재배치 판정용).
95
+ * / Minimum contrast ratio across adjacent color pairs (for test/reorder decisions).
96
+ *
97
+ * @param colors - 색 배열 / Color array
98
+ * @returns 인접쌍 최소 대비비 / The minimum adjacent-pair contrast ratio
99
+ */
36
100
  export declare function minAdjacentContrast(colors: readonly string[]): number;
37
- /** 인접 색쌍의 색약 시뮬 ΔE 최소값(deuteranopia/protanopia 중 나쁜 쪽). 색약 구별 실보증. */
101
+ /**
102
+ * 인접 색쌍의 색약 시뮬 ΔE 최소값(deuteranopia/protanopia 중 나쁜 쪽). 색약 구별 실보증.
103
+ * / Minimum dichromacy-simulated ΔE across adjacent color pairs (the worse of
104
+ * deuteranopia/protanopia). The real guarantee of colorblind distinguishability.
105
+ *
106
+ * @param colors - 색 배열 / Color array
107
+ * @returns 인접쌍 색약 ΔE 최소값 / The minimum adjacent-pair dichromatic ΔE
108
+ */
38
109
  export declare function minAdjacentDichromacyDeltaE(colors: readonly string[]): number;
110
+ /** 결정된 series 표시 스타일(색 + 패턴). / A resolved series display style (color + pattern). */
39
111
  export interface ResolvedSeriesStyle {
112
+ /** 시리즈 색. / Series color. */
40
113
  color: string;
114
+ /** 색 외 구분 패턴. / Redundant (non-color) pattern. */
41
115
  pattern: NonNullable<ChartSeries['pattern']>;
42
116
  }
43
117
  /**
@@ -46,6 +120,16 @@ export interface ResolvedSeriesStyle {
46
120
  * - primary(테마 --og-primary)가 주어지면 첫 팔레트 색으로 유도하되, 다음 색과의
47
121
  * 대비가 3:1 미달이면 안전 팔레트 원본을 그대로 쓴다(§D "fallback으로만").
48
122
  * - 패턴은 인덱스 순환(유일성은 series≤4에서 보장, 초과 시 색+패턴 조합으로 구분).
123
+ * / Resolve per-series color/pattern (§D).
124
+ * - An explicit series.color wins.
125
+ * - A given primary (theme --og-primary) is steered into the first palette slot, but if its
126
+ * contrast against the next color is below 3:1 the original safe palette is kept (§D "fallback only").
127
+ * - Patterns cycle by index (uniqueness is guaranteed for series ≤ 4; beyond that, the color +
128
+ * pattern combination distinguishes them).
129
+ *
130
+ * @param series - 각 series 의 색/패턴 힌트(선택) / Per-series color/pattern hints (optional)
131
+ * @param opts - 팔레트 override·테마 primary(선택) / Palette override and theme primary (optional)
132
+ * @returns series 순서에 맞춘 색+패턴 배열 / An array of color+pattern aligned to series order
49
133
  */
50
134
  export declare function resolveSeriesStyles(series: ReadonlyArray<{
51
135
  color?: string | undefined;
@@ -0,0 +1,12 @@
1
+ import { ChartScene } from './scene.js';
2
+ /**
3
+ * 두 scene 의 1급 파리티(그리기 명령 동일성)를 판정한다. surface(=래스터화 백엔드)는 무관 —
4
+ * 동일 (model,spec,size) 에서 나온 scene 이면 백엔드가 달라도 반드시 동일해야 한다.
5
+ * / Decide first-class parity (draw-command identity) of two scenes. The surface (raster backend)
6
+ * is irrelevant — scenes from identical (model,spec,size) must be equal regardless of backend.
7
+ *
8
+ * @param a - scene A / Scene A
9
+ * @param b - scene B / Scene B
10
+ * @returns 동일하면 true / true if identical
11
+ */
12
+ export declare function sceneEquals(a: ChartScene, b: ChartScene): boolean;