@nanahoshi/mona-ui 0.14.0 → 0.15.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.
- package/chart/README.md +662 -0
- package/chart/package.json +4 -0
- package/fesm2022/nanahoshi-mona-ui-chart.mjs +64226 -0
- package/fesm2022/nanahoshi-mona-ui-tabs.mjs +1 -1
- package/package.json +11 -1
- package/types/nanahoshi-mona-ui-chart.d.ts +7815 -0
package/chart/README.md
ADDED
|
@@ -0,0 +1,662 @@
|
|
|
1
|
+
# @nanahoshi/mona-ui/chart
|
|
2
|
+
|
|
3
|
+
High-performance, accessible, and reactive 2D Canvas Cartesian and Polar chart visualizations designed for modern Angular applications.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
The Mona UI Chart library combines declarative Angular template composition with the rendering speed of HTML5 Canvas 2D. State and inputs are fully reactive with Angular Signals, supporting dynamic resizing, seamless light/dark theming via Tailwind CSS variables, rich tooltip placement, and full WCAG AA accessibility.
|
|
8
|
+
|
|
9
|
+
## Key Features
|
|
10
|
+
|
|
11
|
+
- **Declarative Composition:** Compose charts using intuitive child components for Cartesian axes (`<mona-chart-x-axis>`, `<mona-chart-y-axis>`), Radial axes (`<mona-chart-angular-axis>`, `<mona-chart-radial-axis>`), series, legends, tooltips, inside labels, and donut center templates.
|
|
12
|
+
- **Series Types:**
|
|
13
|
+
- **Cartesian:** Line (with multiple interpolation curves), Area (gradient fade or solid fill), Grouped and Stacked Bar series, Range Bar series (floating min-max interval bars with 4-corner rounded rects), Range Area series (continuous min-max confidence bands and cross-over boundaries), Scatter (point distribution with customizable marker sizes), Bubble series (3-variable mapping with area-proportional square-root radius scaling), Candlestick & OHLC series (financial price action with rising/falling indicators), Heatmap (matrix cell visualization with color scales), Funnel series (conversion pipeline analytics with inscribed labels), and Waterfall series (cashflow and contribution movements with change, subtotal, and total steps).
|
|
14
|
+
- **Sector:** Pie (full or partial circles) and Donut (configurable hole radius ratio and custom center templates).
|
|
15
|
+
- **Polar Axis:** Radar charts (closed polygon series comparing categorical attributes across angular spokes) and Continuous Polar charts (directional signals and curves with continuous angular coordinates from 0° to 360°).
|
|
16
|
+
- **Polar Arc:** Radial Bar series (concentric progress rings), Rose series (Nightingale coxcomb area/radius petals), and Gauge meters (tapered needle and value arc readout).
|
|
17
|
+
- **Hierarchical:** Treemap series (nested squarify, binary, dice, and slice-dice rectangular tiling).
|
|
18
|
+
- **Dynamic & Responsive:** Built-in `ResizeObserver` support with automatic canvas backing store scaling for crisp rendering on HiDPI/Retina screens.
|
|
19
|
+
- **Layering & Composition:** Preserves exact declaration order for mixed series with accurate translucent alpha compositing.
|
|
20
|
+
- **Radial Fill Modes & Gradients:** Solid wash, radial gradient fading from center pole to outer radius, or outline only.
|
|
21
|
+
- **Full Keyboard & Screen Reader Accessibility:**
|
|
22
|
+
- `ArrowRight` / `ArrowLeft`: Navigate through X-axis interaction buckets, polar slices, funnel stages, waterfall steps, or angular spokes.
|
|
23
|
+
- `ArrowUp` / `ArrowDown`: Cycle through visible series at the focused data point or duplicate X coordinates, or navigate slices/levels.
|
|
24
|
+
- `Home` / `End`: Jump to first or last data point/slice/stage.
|
|
25
|
+
- `Enter` / `Space`: Emit click events for the selected data point, spoke, stage, or slice.
|
|
26
|
+
- `Escape`: Dismiss active interaction and announcements.
|
|
27
|
+
- Live ARIA announcements and 100% AXE-compliant accessibility.
|
|
28
|
+
- **Interactive Legend:** Clickable legend items that toggle series or individual slice/stage/ring visibility with stable palette coloring (and semantic presentation legend markers for Waterfall steps).
|
|
29
|
+
- **Customizable Templates:** Custom Angular templates for tooltips (`monaChartTooltipTemplate`), axis tick labels (`monaChartAxisLabelTemplate`), legend items (`monaChartLegendItemTemplate`), slice data labels (`monaChartSliceLabelTemplate`), donut center content (`monaChartCenterTemplate`), gauge center content (`monaChartGaugeCenterTemplate`), treemap node labels (`monaChartTreemapLabelTemplate`), funnel stage labels (`monaChartFunnelLabelTemplate`), waterfall step labels (`monaChartWaterfallLabelTemplate`), and empty states (`monaChartNoDataTemplate`).
|
|
30
|
+
|
|
31
|
+
## High-Density Cartesian Data
|
|
32
|
+
|
|
33
|
+
Downsampling is a render-sample optimization for searchable continuous X axes. The public `algorithm` option is a preference constrained by each series family's semantics; it does not force every family to use a literal reducer with the same name.
|
|
34
|
+
|
|
35
|
+
| Series | Continuous-X reduction | Category-X reduction | Notes |
|
|
36
|
+
| :------------------------- | :--------------------- | :------------------- | :------------------------------------------------------------------------------------------------------------------ |
|
|
37
|
+
| Line | Yes | No | Linear, smooth, `step`, and `step-after` curves use real source points. |
|
|
38
|
+
| Area | Yes | No | Stacked areas use one shared X selection; step members use topology protection. |
|
|
39
|
+
| Range Area | Yes | No | Uses a low/high envelope reducer, including step-safe adjacency. |
|
|
40
|
+
| Scatter / Bubble | Yes | No | Uses spatial/pixel representatives; bubble size keeps its full source domain. |
|
|
41
|
+
| Category-X connected paths | No | No | Discrete category membership and order use viewport culling; automatic point reduction is intentionally ineligible. |
|
|
42
|
+
| Bar / Range Bar | No | No | Discrete marks are not automatically point-sampled. |
|
|
43
|
+
| Candlestick / OHLC | No | No | Financial marks require semantic OHLC aggregation, which is not implicit. |
|
|
44
|
+
| Heatmap / non-Cartesian | No | — | Outside the Cartesian point-density subsystem. |
|
|
45
|
+
|
|
46
|
+
| Requested algorithm | Scalar line/area | Step line/area | Range area | Stack area | Scatter/Bubble |
|
|
47
|
+
| :------------------ | :---------------------- | :----------------- | :---------------- | :----------------------------- | :------------- |
|
|
48
|
+
| `auto` | Indexed scalar | Step-safe | Envelope | Shared stack envelope | Pixel |
|
|
49
|
+
| `minmax` | Min/max | Step-safe | Envelope | Shared stack envelope | Pixel fallback |
|
|
50
|
+
| `lttb` | LTTB | Step-safe fallback | Envelope fallback | Shared stack envelope fallback | Pixel fallback |
|
|
51
|
+
| `pixel` | Connected auto fallback | Step-safe | Envelope fallback | Shared stack envelope fallback | Pixel |
|
|
52
|
+
|
|
53
|
+
Step and step-after series protect source adjacency around selected semantic anchors. Mandatory visible or crossing anchors are reserved before adjacency detail, while `maxPoints` remains a hard cap; when the cap cannot preserve every transition, detail degrades deterministically within that budget.
|
|
54
|
+
|
|
55
|
+
`maxPoints` has family-specific meaning: line, area, and range area count selected defined source marks; scatter and bubble count selected marker candidates; stacked area counts shared timeline X keys for the group. Minimal invalid gap sentinels may appear internally to preserve disconnected-path topology, but they are not selected data marks. Raw pointer, brush, selection, and tooltip interaction may still resolve an unsampled source datum through the retained interaction provider. Unsorted or unsearchable X data safely keeps source-order full layout because sorting it would change connected-path semantics. Keyboard navigation intentionally remains bounded to the rendered sample.
|
|
56
|
+
|
|
57
|
+
Eligibility and activation are separate. A source below the activation threshold uses ordinary full rendering; it is not a capability failure. An explicit `maxPoints` can activate reduction below that threshold for an eligible continuous-X family. Category X remains a discrete viewport-culling policy, while unsorted, unsearchable, or non-finite X remains intentionally ineligible so connected-path source order is preserved.
|
|
58
|
+
|
|
59
|
+
### Dense runtime ownership and stress workflow
|
|
60
|
+
|
|
61
|
+
The dense runtime has three ownership layers: source-semantic authority, viewport/sample membership, and projected scene geometry. Source authority is tied to a semantic data generation and is reused for viewport, resize, and projection-only updates. Samples and projections retain compact source indexes; they do not become a replacement identity authority. Duplicate-key occurrence metadata is allocated only when duplicate semantic keys require it.
|
|
62
|
+
|
|
63
|
+
When source semantics change, the previous dense runtime is invalidated before the replacement is prepared. Chart destruction releases source-dependent identity state and drops the retained scene. The million-row regression cases live in `*.stress.spec.ts` and run through the serial, non-coverage target:
|
|
64
|
+
|
|
65
|
+
```text
|
|
66
|
+
npm run test:lib
|
|
67
|
+
npm run test:lib:density-stress
|
|
68
|
+
npm run test:lib:density-bench
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
The one-worker stress policy is a resource boundary for those deliberately large cases; it is not a substitute for bounded source ownership or viewport cache reuse.
|
|
72
|
+
|
|
73
|
+
The benchmark is intentionally non-gating and emits one compact JSON record for each 10k, 100k, 250k, and 1M source size. It measures normalization/index construction, lazy identity setup, 50 viewport index queries, source replacement, teardown release, and process memory before/after the run.
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## Basic Usage
|
|
78
|
+
|
|
79
|
+
### Scatter Chart
|
|
80
|
+
|
|
81
|
+
```html
|
|
82
|
+
<mona-chart [data]="experimentalData" xField="temperature" aria-label="Temperature vs Pressure" class="h-80 w-full">
|
|
83
|
+
<mona-chart-x-axis type="linear" [nice]="true" />
|
|
84
|
+
<mona-chart-y-axis [nice]="true" />
|
|
85
|
+
|
|
86
|
+
<mona-scatter-series field="pressure" name="Sample A" [pointRadius]="6" color="#3b82f6" />
|
|
87
|
+
<mona-scatter-series field="controlPressure" name="Control" [pointRadius]="4" color="#94a3b8" />
|
|
88
|
+
|
|
89
|
+
<mona-chart-legend position="bottom" [interactive]="true" />
|
|
90
|
+
<mona-chart-tooltip [shared]="false" />
|
|
91
|
+
</mona-chart>
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### Bubble Chart
|
|
95
|
+
|
|
96
|
+
```html
|
|
97
|
+
<mona-chart [data]="marketData" xField="growthRate" aria-label="Market Capitalization vs Growth" class="h-80 w-full">
|
|
98
|
+
<mona-chart-x-axis type="linear" [nice]="true" />
|
|
99
|
+
<mona-chart-y-axis [nice]="true" />
|
|
100
|
+
|
|
101
|
+
<mona-bubble-series
|
|
102
|
+
field="revenue"
|
|
103
|
+
sizeField="marketCap"
|
|
104
|
+
name="Tech Enterprises"
|
|
105
|
+
[minRadius]="4"
|
|
106
|
+
[maxRadius]="28"
|
|
107
|
+
color="#10b981"
|
|
108
|
+
[fillOpacity]="0.5" />
|
|
109
|
+
|
|
110
|
+
<mona-chart-legend position="bottom" [interactive]="true" />
|
|
111
|
+
<mona-chart-tooltip [shared]="false" />
|
|
112
|
+
</mona-chart>
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Radar Chart
|
|
116
|
+
|
|
117
|
+
```html
|
|
118
|
+
<mona-chart [data]="characterStats" aria-label="Character Skill Matrix" class="h-80 w-full">
|
|
119
|
+
<mona-chart-angular-axis />
|
|
120
|
+
<mona-chart-radial-axis gridShape="polygon" [nice]="true" />
|
|
121
|
+
|
|
122
|
+
<mona-radar-series
|
|
123
|
+
field="warrior"
|
|
124
|
+
categoryField="metric"
|
|
125
|
+
name="Warrior"
|
|
126
|
+
fillMode="gradient"
|
|
127
|
+
curve="linear"
|
|
128
|
+
[showPoints]="true" />
|
|
129
|
+
<mona-radar-series
|
|
130
|
+
field="mage"
|
|
131
|
+
categoryField="metric"
|
|
132
|
+
name="Mage"
|
|
133
|
+
fillMode="gradient"
|
|
134
|
+
curve="linear"
|
|
135
|
+
[showPoints]="true" />
|
|
136
|
+
|
|
137
|
+
<mona-chart-legend position="bottom" [interactive]="true" />
|
|
138
|
+
<mona-chart-tooltip [shared]="true" />
|
|
139
|
+
</mona-chart>
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Continuous Polar Chart
|
|
143
|
+
|
|
144
|
+
```html
|
|
145
|
+
<mona-chart [data]="radiationData" aria-label="Antenna Radiation Pattern" class="h-80 w-full">
|
|
146
|
+
<mona-chart-angular-axis [tickCount]="12" />
|
|
147
|
+
<mona-chart-radial-axis gridShape="circle" [nice]="true" />
|
|
148
|
+
|
|
149
|
+
<mona-polar-series
|
|
150
|
+
field="gain"
|
|
151
|
+
angleField="angle"
|
|
152
|
+
name="Gain (dBi)"
|
|
153
|
+
fillMode="gradient"
|
|
154
|
+
curve="smooth"
|
|
155
|
+
[showPoints]="true" />
|
|
156
|
+
|
|
157
|
+
<mona-chart-legend position="bottom" [interactive]="true" />
|
|
158
|
+
<mona-chart-tooltip [shared]="true" />
|
|
159
|
+
</mona-chart>
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### Cartesian Mixed Chart (Bar, Line, Area, Scatter)
|
|
163
|
+
|
|
164
|
+
```html
|
|
165
|
+
<mona-chart [data]="salesData" xField="month" aria-label="Monthly Sales Performance" class="h-80 w-full">
|
|
166
|
+
<mona-chart-x-axis type="category" />
|
|
167
|
+
<mona-chart-y-axis [nice]="true" />
|
|
168
|
+
|
|
169
|
+
<mona-bar-series field="revenue" name="Revenue" [borderRadius]="4" />
|
|
170
|
+
<mona-line-series field="target" name="Target" curve="monotone-x" [showPoints]="true" />
|
|
171
|
+
<mona-area-series field="forecast" name="Forecast" fillMode="gradient" />
|
|
172
|
+
|
|
173
|
+
<mona-chart-legend position="bottom" [interactive]="true" />
|
|
174
|
+
<mona-chart-tooltip [shared]="true" />
|
|
175
|
+
</mona-chart>
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
### Stacked Bar Chart & 100% Stacked Bar Chart
|
|
179
|
+
|
|
180
|
+
```html
|
|
181
|
+
<mona-chart [data]="salesData" xField="quarter" aria-label="Quarterly Revenue by Region" class="h-80 w-full">
|
|
182
|
+
<mona-chart-x-axis type="category" />
|
|
183
|
+
<mona-chart-y-axis [nice]="true" />
|
|
184
|
+
|
|
185
|
+
<!-- Grouped or 100% Stacked: assign the same stack group identifier -->
|
|
186
|
+
<mona-bar-series field="north" name="North America" stack="sales" [borderRadius]="4" />
|
|
187
|
+
<mona-bar-series field="europe" name="Europe" stack="sales" [borderRadius]="4" />
|
|
188
|
+
<mona-bar-series field="asia" name="Asia Pacific" stack="sales" [borderRadius]="4" />
|
|
189
|
+
|
|
190
|
+
<mona-chart-legend position="bottom" [interactive]="true" />
|
|
191
|
+
<mona-chart-tooltip [shared]="true" />
|
|
192
|
+
</mona-chart>
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
### Stacked Area Chart & 100% Stacked Area Chart
|
|
196
|
+
|
|
197
|
+
```html
|
|
198
|
+
<mona-chart [data]="trafficData" xField="year" aria-label="Web Traffic Composition" class="h-80 w-full">
|
|
199
|
+
<mona-chart-x-axis type="linear" />
|
|
200
|
+
<mona-chart-y-axis [nice]="true" />
|
|
201
|
+
|
|
202
|
+
<mona-area-series field="organic" name="Organic Search" stack="traffic" fillMode="gradient" />
|
|
203
|
+
<mona-area-series field="referral" name="Referral" stack="traffic" fillMode="gradient" />
|
|
204
|
+
<mona-area-series field="direct" name="Direct" stack="traffic" fillMode="gradient" />
|
|
205
|
+
|
|
206
|
+
<mona-chart-legend position="bottom" [interactive]="true" />
|
|
207
|
+
<mona-chart-tooltip [shared]="true" />
|
|
208
|
+
</mona-chart>
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
### Pie & Donut Charts
|
|
212
|
+
|
|
213
|
+
```html
|
|
214
|
+
<mona-chart [data]="browserShare" aria-label="Browser Usage Share" class="h-80 w-full">
|
|
215
|
+
<mona-pie-series field="share" categoryField="browser" [showLabels]="true" labelContent="percentage" />
|
|
216
|
+
|
|
217
|
+
<mona-chart-legend position="bottom" [interactive]="true" />
|
|
218
|
+
<mona-chart-tooltip />
|
|
219
|
+
</mona-chart>
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
## Components & Directives
|
|
225
|
+
|
|
226
|
+
### `<mona-chart>`
|
|
227
|
+
|
|
228
|
+
The root container that coordinates layout measurement, data domains, rendering schedules, animation transitions, and interaction.
|
|
229
|
+
|
|
230
|
+
| Input / Output | Type | Default | Description |
|
|
231
|
+
| :----------------------- | :----------------------------------- | :-------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
|
|
232
|
+
| `data` | `readonly unknown[]` | `[]` | Primary dataset shared across all child series. |
|
|
233
|
+
| `xField` | `ChartField` | `""` | Property key or accessor extracting the X-axis coordinate for each data item. |
|
|
234
|
+
| `title` | `string` | `""` | Title text rendered at the top of the chart above the plot area. |
|
|
235
|
+
| `subtitle` | `string` | `""` | Subtitle text rendered beneath the title. |
|
|
236
|
+
| `titleAlign` | `ChartHeaderAlignment` | `"left"` | Alignment of the chart title and subtitle (`"center"`, `"left"`, or `"right"`). |
|
|
237
|
+
| `animation` | `ChartAnimationInput` | `true` | Animation settings (`boolean` or `Partial<ChartAnimationOptions>`) for initial render, data transitions, and series visibility toggles. |
|
|
238
|
+
| `ariaLabel` | `string` | `"Chart"` | Accessible name for the chart container (falls back to `title`). |
|
|
239
|
+
| `ariaDescription` | `string` | `""` | Detailed accessible description explaining the chart's purpose and trends (falls back to `subtitle`). |
|
|
240
|
+
| `pointClick` | `output<ChartPointEvent>` | — | Emits when a data point, vertex, bar, marker, or sector slice is clicked. |
|
|
241
|
+
| `pointFocusChange` | `output<ChartPointFocusEvent>` | — | Emits when keyboard focus moves to a new data point, marker, spoke, or slice. |
|
|
242
|
+
| `seriesVisibilityChange` | `output<ChartSeriesVisibilityEvent>` | — | Emits when a series visibility state is toggled via legend interaction. |
|
|
243
|
+
|
|
244
|
+
### Cartesian Axes (`<mona-chart-x-axis>`, `<mona-chart-y-axis>`)
|
|
245
|
+
|
|
246
|
+
| Input | Type | Default | Description |
|
|
247
|
+
| :-------------- | :----------------------- | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
|
|
248
|
+
| `axisLine` | `boolean` | `true` | Whether to draw the baseline border axis line. |
|
|
249
|
+
| `gridLines` | `boolean` | `auto` | Whether to render orthogonal grid lines across the plot area (default `false` on X, `true` on Y in vertical charts). |
|
|
250
|
+
| `labels` | `boolean` | `true` | Whether to render tick labels. |
|
|
251
|
+
| `labelRotation` | `ChartAxisLabelRotation` | `0` | Axis label rotation in degrees (`-90` to `90`) or `"auto"` (auto-rotates to -45° when labels collide on physical X category axis). |
|
|
252
|
+
| `labelPadding` | `number` | `4` | Spacing in pixels between the baseline/tick marks and the label bounds. |
|
|
253
|
+
| `labelMaxWidth` | `number` | `undefined` | Optional maximum width in pixels applied to label spans with text truncation. |
|
|
254
|
+
| `tickMarks` | `boolean` | `false` | Whether to render outward tick marks along the axis baseline. |
|
|
255
|
+
| `tickSize` | `number` | `6` | Length in pixels of outward tick marks. |
|
|
256
|
+
| `titlePadding` | `number` | `8` | Spacing in pixels between the outer label edge and the axis title. |
|
|
257
|
+
| `position` | `string` | `"bottom"` / `"left"` | Axis placement (`"bottom"` or `"top"` for X; `"left"` or `"right"` for Y). |
|
|
258
|
+
| `min` / `max` | `number \| Date` | `undefined` | Explicit domain bounds for continuous scales. |
|
|
259
|
+
| `nice` | `boolean` | `true` | Rounds continuous domain bounds to clean tick increments. |
|
|
260
|
+
| `tickCount` | `number` | `5` | Desired tick mark frequency for continuous scales or preferred maximum tick cap for category axes. |
|
|
261
|
+
| `visible` | `boolean` | `true` | Whether the axis is visible. |
|
|
262
|
+
|
|
263
|
+
### Animation & Transitions
|
|
264
|
+
|
|
265
|
+
Mona UI Charts feature a high-performance, renderer-agnostic animation system:
|
|
266
|
+
|
|
267
|
+
- **Geometry Morphing:** Smoothly interpolates Cartesian bars from baselines, line/area paths, sector arcs, radial polygons, and markers (interpolating positions, radii, and opacities).
|
|
268
|
+
- **Stable Identity:** Use the `keyField` input on series components to track items across reorders, additions, and deletions.
|
|
269
|
+
- **CSS Custom Properties:** Exposes `--mona-chart-animation-duration` and `--mona-chart-animation-easing` on the chart host element for synchronized CSS transitions.
|
|
270
|
+
- **Reduced Motion:** Automatically respects `prefers-reduced-motion: reduce` by completing transitions immediately without motion.
|
|
271
|
+
|
|
272
|
+
### Range Bar Chart
|
|
273
|
+
|
|
274
|
+
```html
|
|
275
|
+
<mona-chart [data]="temperatureRanges" xField="day" aria-label="Daily Temperature Ranges" class="h-80 w-full">
|
|
276
|
+
<mona-chart-x-axis type="category" />
|
|
277
|
+
<mona-chart-y-axis [nice]="true" />
|
|
278
|
+
|
|
279
|
+
<mona-range-bar-series
|
|
280
|
+
fromField="minTemp"
|
|
281
|
+
toField="maxTemp"
|
|
282
|
+
name="Daily Range"
|
|
283
|
+
[borderRadius]="4"
|
|
284
|
+
color="#3b82f6" />
|
|
285
|
+
|
|
286
|
+
<mona-chart-legend position="bottom" [interactive]="true" />
|
|
287
|
+
<mona-chart-tooltip [shared]="false" />
|
|
288
|
+
</mona-chart>
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
### Range Area Chart
|
|
292
|
+
|
|
293
|
+
```html
|
|
294
|
+
<mona-chart [data]="sensorConfidence" xField="timestamp" aria-label="Sensor Confidence Interval" class="h-80 w-full">
|
|
295
|
+
<mona-chart-x-axis type="time" />
|
|
296
|
+
<mona-chart-y-axis [nice]="true" />
|
|
297
|
+
|
|
298
|
+
<mona-range-area-series
|
|
299
|
+
fromField="lowerBound"
|
|
300
|
+
toField="upperBound"
|
|
301
|
+
name="95% Confidence Band"
|
|
302
|
+
curve="monotone-x"
|
|
303
|
+
[showPoints]="true"
|
|
304
|
+
color="#10b981"
|
|
305
|
+
[fillOpacity]="0.25" />
|
|
306
|
+
|
|
307
|
+
<mona-chart-legend position="bottom" [interactive]="true" />
|
|
308
|
+
<mona-chart-tooltip [shared]="true" />
|
|
309
|
+
</mona-chart>
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
### `<mona-bar-series>`
|
|
313
|
+
|
|
314
|
+
Renders a Cartesian bar series supporting standalone bars, grouped slots, stacked segments, and 100% normalized stacks.
|
|
315
|
+
|
|
316
|
+
| Input / Output | Type | Default | Description |
|
|
317
|
+
| :--------------- | :-------------------- | :----------- | :---------------------------------------------------------------------------------------------------------- |
|
|
318
|
+
| `field` | `ChartField` | `"value"` | Property key or accessor extracting numeric bar height/value. |
|
|
319
|
+
| `xField` | `ChartField` | `undefined` | Property key or accessor extracting X-axis coordinate (overrides chart-level `xField`). |
|
|
320
|
+
| `keyField` | `ChartField` | `undefined` | Unique identifier field for stable mark tracking across animation transitions. |
|
|
321
|
+
| `name` | `string` | `"Bar"` | Series name for tooltips, legend, and accessibility. |
|
|
322
|
+
| `orientation` | `ChartBarOrientation` | `"vertical"` | Bar orientation: `"vertical"` (category on X, value on Y) or `"horizontal"` (category on Y, value on X). |
|
|
323
|
+
| `stack` | `string` | `undefined` | Stack group name. Series sharing the same stack identifier are stacked cumulatively into a single bar slot. |
|
|
324
|
+
| `stackMode` | `ChartStackMode` | `"normal"` | Stacking calculation mode: `"normal"` (raw cumulative sum) or `"percent"` (normalized to 100%). |
|
|
325
|
+
| `borderRadius` | `number` | `0` | Corner radius for the outer cap of the bar/stack. |
|
|
326
|
+
| `maxBarWidth` | `number` | `undefined` | Maximum width/height of the bar in pixels. |
|
|
327
|
+
| `color` | `string` | `undefined` | Bar fill color. Defaults to palette token. |
|
|
328
|
+
| `fillOpacity` | `number` | `1.0` | Bar fill opacity between 0.0 and 1.0. |
|
|
329
|
+
| `valueFormatter` | `ChartValueFormatter` | `undefined` | Custom formatter callback for bar raw values and stack totals in tooltips and live region. |
|
|
330
|
+
| `visible` | `model(boolean)` | `true` | Two-way bindable series visibility. |
|
|
331
|
+
|
|
332
|
+
### `<mona-range-bar-series>`
|
|
333
|
+
|
|
334
|
+
Renders a Cartesian floating range bar series plotting discrete min-max intervals with 4-corner rounded rects and zero-length hairlines.
|
|
335
|
+
|
|
336
|
+
| Input / Output | Type | Default | Description |
|
|
337
|
+
| :--------------- | :-------------------- | :------------ | :-------------------------------------------------------------------------------------- |
|
|
338
|
+
| `fromField` | `ChartField` | (required) | Property key or accessor extracting the range starting/lower value. |
|
|
339
|
+
| `toField` | `ChartField` | (required) | Property key or accessor extracting the range ending/upper value. |
|
|
340
|
+
| `xField` | `ChartField` | `undefined` | Property key or accessor extracting X-axis coordinate (overrides chart-level `xField`). |
|
|
341
|
+
| `orientation` | `ChartBarOrientation` | `"vertical"` | Bar orientation: `"vertical"` or `"horizontal"`. |
|
|
342
|
+
| `keyField` | `ChartField` | `undefined` | Unique identifier field for stable mark tracking across animation transitions. |
|
|
343
|
+
| `name` | `string` | `"Range Bar"` | Series name for tooltips, legend, and accessibility. |
|
|
344
|
+
| `borderRadius` | `number` | `4` | Corner radius applied to all 4 corners of floating bars. |
|
|
345
|
+
| `maxBarWidth` | `number` | `undefined` | Maximum width/height of the bar in pixels. |
|
|
346
|
+
| `color` | `string` | `undefined` | Bar fill color. Defaults to palette token. |
|
|
347
|
+
| `fillOpacity` | `number` | `1.0` | Bar fill opacity between 0.0 and 1.0. |
|
|
348
|
+
| `valueFormatter` | `ChartValueFormatter` | `undefined` | Custom formatter callback for formatting range bounds in tooltips and live region. |
|
|
349
|
+
| `visible` | `model(boolean)` | `true` | Two-way bindable series visibility. |
|
|
350
|
+
|
|
351
|
+
### `<mona-area-series>`
|
|
352
|
+
|
|
353
|
+
Renders a continuous Cartesian area series supporting gradient fades, solid fills, cumulative stacking, and 100% normalized area bands.
|
|
354
|
+
|
|
355
|
+
| Input / Output | Type | Default | Description |
|
|
356
|
+
| :--------------- | :-------------------- | :----------- | :------------------------------------------------------------------------------------------------- |
|
|
357
|
+
| `field` | `ChartField` | `"value"` | Property key or accessor extracting numeric Y value. |
|
|
358
|
+
| `xField` | `ChartField` | `undefined` | Property key or accessor extracting X-axis coordinate (overrides chart-level `xField`). |
|
|
359
|
+
| `keyField` | `ChartField` | `undefined` | Unique identifier field for stable mark tracking across animation transitions. |
|
|
360
|
+
| `name` | `string` | `"Area"` | Series name for tooltips, legend, and accessibility. |
|
|
361
|
+
| `stack` | `string` | `undefined` | Stack group name. Series sharing the same stack identifier are stacked into cumulative bands. |
|
|
362
|
+
| `stackMode` | `ChartStackMode` | `"normal"` | Stacking calculation mode: `"normal"` (raw cumulative sum) or `"percent"` (normalized to 100%). |
|
|
363
|
+
| `fillMode` | `ChartAreaFillMode` | `"gradient"` | Area fill style: `"gradient"`, `"solid"`, or `"none"`. |
|
|
364
|
+
| `fillOpacity` | `number` | `0.2` | Area fill opacity between 0.0 and 1.0. |
|
|
365
|
+
| `curve` | `ChartCurve` | `"linear"` | Curve interpolation algorithm (`"linear"`, `"monotone-x"`, `"natural"`, `"step"`, `"step-after"`). |
|
|
366
|
+
| `connectNulls` | `boolean` | `false` | Whether to interpolate across null/missing data points. |
|
|
367
|
+
| `showPoints` | `boolean` | `false` | Whether to render point markers at data coordinates. |
|
|
368
|
+
| `color` | `string` | `undefined` | Area line and fill color. Defaults to palette token. |
|
|
369
|
+
| `valueFormatter` | `ChartValueFormatter` | `undefined` | Custom formatter callback for area raw values and stack totals in tooltips and live region. |
|
|
370
|
+
| `visible` | `model(boolean)` | `true` | Two-way bindable series visibility. |
|
|
371
|
+
|
|
372
|
+
### `<mona-range-area-series>`
|
|
373
|
+
|
|
374
|
+
Renders a continuous Cartesian range area series enclosing a confidence or variance band between two continuous boundary lines.
|
|
375
|
+
|
|
376
|
+
| Input / Output | Type | Default | Description |
|
|
377
|
+
| :--------------- | :-------------------- | :------------- | :------------------------------------------------------------------------------------------------- |
|
|
378
|
+
| `fromField` | `ChartField` | (required) | Property key or accessor extracting the range starting boundary value. |
|
|
379
|
+
| `toField` | `ChartField` | (required) | Property key or accessor extracting the range ending boundary value. |
|
|
380
|
+
| `xField` | `ChartField` | `undefined` | Property key or accessor extracting X-axis coordinate (overrides chart-level `xField`). |
|
|
381
|
+
| `keyField` | `ChartField` | `undefined` | Unique identifier field for stable mark tracking across animation transitions. |
|
|
382
|
+
| `name` | `string` | `"Range Area"` | Series name for tooltips, legend, and accessibility. |
|
|
383
|
+
| `fillOpacity` | `number` | `0.18` | Range band fill opacity between 0.0 and 1.0. |
|
|
384
|
+
| `curve` | `ChartCurve` | `"linear"` | Curve interpolation algorithm (`"linear"`, `"monotone-x"`, `"natural"`, `"step"`, `"step-after"`). |
|
|
385
|
+
| `connectNulls` | `boolean` | `false` | Whether to interpolate across null/missing data points. |
|
|
386
|
+
| `showPoints` | `boolean` | `false` | Whether to render point markers at boundary coordinates. |
|
|
387
|
+
| `pointRadius` | `number` | `4` | Boundary marker radius in pixels when `showPoints` is true. |
|
|
388
|
+
| `strokeWidth` | `number` | `2` | Boundary outline stroke width in pixels. |
|
|
389
|
+
| `color` | `string` | `undefined` | Range band line and fill color. Defaults to palette token. |
|
|
390
|
+
| `valueFormatter` | `ChartValueFormatter` | `undefined` | Custom formatter callback for formatting range bounds in tooltips and live region. |
|
|
391
|
+
| `visible` | `model(boolean)` | `true` | Two-way bindable series visibility. |
|
|
392
|
+
|
|
393
|
+
### `<mona-scatter-series>`
|
|
394
|
+
|
|
395
|
+
Renders a Cartesian scatter series representing individual points along continuous linear or temporal X and Y dimensions.
|
|
396
|
+
|
|
397
|
+
| Input / Output | Type | Default | Description |
|
|
398
|
+
| :------------- | :--------------- | :---------- | :-------------------------------------------------------------------------------------- |
|
|
399
|
+
| `field` | `ChartField` | `"value"` | Property key or accessor extracting numeric Y-axis coordinate. |
|
|
400
|
+
| `xField` | `ChartField` | `undefined` | Property key or accessor extracting X-axis coordinate (overrides chart-level `xField`). |
|
|
401
|
+
| `keyField` | `ChartField` | `undefined` | Unique identifier field for stable mark tracking across animation transitions. |
|
|
402
|
+
| `name` | `string` | `"Scatter"` | Series name for tooltips, legend, and accessibility. |
|
|
403
|
+
| `color` | `string` | `undefined` | Series mark color. Defaults to palette token. |
|
|
404
|
+
| `pointRadius` | `number` | `undefined` | Marker circle radius in pixels. Defaults to `--mona-chart-point-radius` (4px). |
|
|
405
|
+
| `fillOpacity` | `number` | `0.9` | Fill opacity between 0.0 and 1.0. |
|
|
406
|
+
| `strokeColor` | `string` | `"#ffffff"` | Border stroke color. |
|
|
407
|
+
| `strokeWidth` | `number` | `1.5` | Border stroke width in pixels. |
|
|
408
|
+
| `visible` | `model(boolean)` | `true` | Two-way bindable series visibility. |
|
|
409
|
+
|
|
410
|
+
### `<mona-bubble-series>`
|
|
411
|
+
|
|
412
|
+
Renders a Cartesian bubble series encoding a 3rd quantitative dimension into mark area using area-proportional square-root radius mapping.
|
|
413
|
+
|
|
414
|
+
| Input / Output | Type | Default | Description |
|
|
415
|
+
| :-------------- | :---------------------------- | :---------- | :--------------------------------------------------------------------------------------------------------------- |
|
|
416
|
+
| `field` | `ChartField` | `"value"` | Property key or accessor extracting numeric Y-axis coordinate. |
|
|
417
|
+
| `sizeField` | `ChartField` | `"size"` | Property key or accessor extracting quantitative magnitude for bubble area. |
|
|
418
|
+
| `sizeFormatter` | `ChartValueFormatter<number>` | `undefined` | Formatter callback generating formatted size strings for tooltips and accessibility announcements. |
|
|
419
|
+
| `minRadius` | `number` | `undefined` | Minimum bubble radius in pixels for the minimum size value. Defaults to `--mona-chart-bubble-min-radius` (4px). |
|
|
420
|
+
| `maxRadius` | `number` | `undefined` | Maximum bubble radius in pixels for the maximum size value. Defaults to `--mona-chart-bubble-max-radius` (24px). |
|
|
421
|
+
| `xField` | `ChartField` | `undefined` | Property key or accessor extracting X-axis coordinate (overrides chart-level `xField`). |
|
|
422
|
+
| `keyField` | `ChartField` | `undefined` | Unique identifier field for stable mark tracking across animation transitions. |
|
|
423
|
+
| `name` | `string` | `"Bubble"` | Series name for tooltips, legend, and accessibility. |
|
|
424
|
+
| `color` | `string` | `undefined` | Series mark color. Defaults to palette token. |
|
|
425
|
+
| `fillOpacity` | `number` | `0.55` | Fill opacity between 0.0 and 1.0. |
|
|
426
|
+
| `strokeColor` | `string` | `"#ffffff"` | Border stroke color. |
|
|
427
|
+
| `strokeWidth` | `number` | `1.5` | Border stroke width in pixels. |
|
|
428
|
+
| `visible` | `model(boolean)` | `true` | Two-way bindable series visibility. |
|
|
429
|
+
|
|
430
|
+
### CSS Variables for Styling
|
|
431
|
+
|
|
432
|
+
Mona UI Charts support theme customization via standard CSS custom properties:
|
|
433
|
+
|
|
434
|
+
```css
|
|
435
|
+
:root {
|
|
436
|
+
--mona-chart-point-radius: 5px;
|
|
437
|
+
--mona-chart-bubble-min-radius: 4px;
|
|
438
|
+
--mona-chart-bubble-max-radius: 28px;
|
|
439
|
+
--mona-chart-focus-indicator-color: #3b82f6;
|
|
440
|
+
--mona-chart-focus-indicator-width: 2px;
|
|
441
|
+
}
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
### `<mona-chart-angular-axis>`
|
|
445
|
+
|
|
446
|
+
Configures the angular (spoke / degree) dimension in Polar and Radar charts.
|
|
447
|
+
|
|
448
|
+
| Input | Type | Default | Description |
|
|
449
|
+
| :---------- | :-------- | :------ | :--------------------------------------------------------------------------- |
|
|
450
|
+
| `axisLine` | `boolean` | `true` | Whether to render the outer circular/polygonal border axis line. |
|
|
451
|
+
| `gridLines` | `boolean` | `true` | Whether to render radiating spoke lines from the pole to the outer boundary. |
|
|
452
|
+
| `labels` | `boolean` | `true` | Whether to render angular category/degree labels. |
|
|
453
|
+
| `rotation` | `number` | `0` | Angle rotation in degrees (clockwise) of the 0° reference position. |
|
|
454
|
+
| `tickCount` | `number` | `12` | Desired number of angular ticks for continuous polar charts. |
|
|
455
|
+
| `visible` | `boolean` | `true` | Whether the angular axis is visible. |
|
|
456
|
+
|
|
457
|
+
### `<mona-chart-radial-axis>`
|
|
458
|
+
|
|
459
|
+
Configures the radial (distance from center pole) dimension in Polar and Radar charts.
|
|
460
|
+
|
|
461
|
+
| Input | Type | Default | Description |
|
|
462
|
+
| :------------ | :--------------------- | :---------- | :--------------------------------------------------------------------------------------------------------- |
|
|
463
|
+
| `axisLine` | `boolean` | `true` | Whether to render the zero center tick indicator. |
|
|
464
|
+
| `gridLines` | `boolean` | `true` | Whether to render concentric radial grid rings. |
|
|
465
|
+
| `gridShape` | `ChartRadialGridShape` | `"auto"` | Concentric grid ring geometry: `"auto"` (polygon for radar, circle for polar), `"polygon"`, or `"circle"`. |
|
|
466
|
+
| `labels` | `boolean` | `true` | Whether to render numeric radial tick labels along the primary reference spoke. |
|
|
467
|
+
| `min` / `max` | `number` | `undefined` | Explicit radial domain bounds. |
|
|
468
|
+
| `nice` | `boolean` | `true` | Rounds radial min/max bounds to human-friendly tick increments. |
|
|
469
|
+
| `visible` | `boolean` | `true` | Whether the radial axis is visible. |
|
|
470
|
+
|
|
471
|
+
### `<mona-radar-series>`
|
|
472
|
+
|
|
473
|
+
Renders a closed polygonal series comparing categorical metrics across angular spokes.
|
|
474
|
+
|
|
475
|
+
| Input / Output | Type | Default | Description |
|
|
476
|
+
| :-------------- | :-------------------- | :----------- | :----------------------------------------------------------------------------- |
|
|
477
|
+
| `field` | `ChartField` | `"value"` | Property key or accessor extracting numeric metric value. |
|
|
478
|
+
| `categoryField` | `ChartField` | `"category"` | Property key or accessor extracting spoke category. |
|
|
479
|
+
| `keyField` | `ChartField` | `undefined` | Unique identifier field for stable mark tracking across animation transitions. |
|
|
480
|
+
| `name` | `string` | `"Radar"` | Series name for tooltips, legend, and accessibility. |
|
|
481
|
+
| `fillMode` | `ChartRadialFillMode` | `"solid"` | Fill styling: `"solid"` wash, radial `"gradient"`, or `"none"`. |
|
|
482
|
+
| `curve` | `ChartRadialCurve` | `"linear"` | Curve interpolation: `"linear"` or `"smooth"` (closed Catmull-Rom spline). |
|
|
483
|
+
| `showPoints` | `boolean` | `true` | Whether vertex point markers are rendered. |
|
|
484
|
+
| `pointRadius` | `number` | `undefined` | Vertex marker radius in pixels. |
|
|
485
|
+
| `strokeWidth` | `number` | `undefined` | Polygon outline stroke width in pixels. |
|
|
486
|
+
| `visible` | `model(boolean)` | `true` | Two-way bindable series visibility. |
|
|
487
|
+
|
|
488
|
+
### `<mona-polar-series>`
|
|
489
|
+
|
|
490
|
+
Renders a continuous polar series plotting values over continuous angular degrees (0° to 360°).
|
|
491
|
+
|
|
492
|
+
| Input / Output | Type | Default | Description |
|
|
493
|
+
| :------------- | :-------------------- | :---------- | :----------------------------------------------------------------------------- |
|
|
494
|
+
| `field` | `ChartField` | `"value"` | Property key or accessor extracting numeric radial magnitude. |
|
|
495
|
+
| `angleField` | `ChartField` | `"angle"` | Property key or accessor extracting angle in degrees. |
|
|
496
|
+
| `keyField` | `ChartField` | `undefined` | Unique identifier field for stable mark tracking across animation transitions. |
|
|
497
|
+
| `name` | `string` | `"Polar"` | Series name for tooltips, legend, and accessibility. |
|
|
498
|
+
| `fillMode` | `ChartRadialFillMode` | `"none"` | Fill styling: `"solid"` wash, radial `"gradient"` (to pole), or `"none"`. |
|
|
499
|
+
| `curve` | `ChartRadialCurve` | `"linear"` | Curve interpolation: `"linear"` or `"smooth"`. |
|
|
500
|
+
| `connectNulls` | `boolean` | `false` | Whether to interpolate across null/undefined values. |
|
|
501
|
+
| `showPoints` | `boolean` | `false` | Whether data point markers are rendered. |
|
|
502
|
+
| `visible` | `model(boolean)` | `true` | Two-way bindable series visibility. |
|
|
503
|
+
|
|
504
|
+
### `<mona-heatmap-series>`
|
|
505
|
+
|
|
506
|
+
Renders a 2D matrix heatmap visualization with perceptual Culori color scale interpolation and keyboard navigation.
|
|
507
|
+
|
|
508
|
+
| Input / Output | Type | Default | Description |
|
|
509
|
+
| :--------------- | :---------------------- | :------------- | :-------------------------------------------------------------------------------------------- |
|
|
510
|
+
| `data` | `readonly unknown[]` | `undefined` | Matrix cell dataset or sparse records. |
|
|
511
|
+
| `field` | `ChartField` | `"value"` | Property key or accessor extracting numeric heat value. |
|
|
512
|
+
| `xField` | `ChartField` | `"x"` | Property key or accessor extracting X category column. |
|
|
513
|
+
| `yField` | `ChartField` | `"y"` | Property key or accessor extracting Y category row. |
|
|
514
|
+
| `keyField` | `ChartField` | `undefined` | Unique identifier field for stable cell mark tracking across animation transitions. |
|
|
515
|
+
| `color` | `string` | `undefined` | Custom single base color for sequential ramp generation. |
|
|
516
|
+
| `colors` | `readonly string[]` | `undefined` | Custom palette stops for color interpolation. |
|
|
517
|
+
| `colorMode` | `ChartHeatmapColorMode` | `"sequential"` | Color scale mode: `"sequential"` or `"diverging"`. |
|
|
518
|
+
| `min` | `number` | `undefined` | Explicit minimum domain value for color scale. |
|
|
519
|
+
| `max` | `number` | `undefined` | Explicit maximum domain value for color scale. |
|
|
520
|
+
| `midpoint` | `number` | `undefined` | Explicit midpoint value for diverging color scales (defaults to `(min + max) / 2`). |
|
|
521
|
+
| `cellGap` | `number` | `1` | Pixel gap between matrix cells. |
|
|
522
|
+
| `borderRadius` | `number` | `0` | Corner border radius in pixels for each cell rectangle. |
|
|
523
|
+
| `strokeColor` | `string` | `undefined` | Optional cell border outline color. |
|
|
524
|
+
| `strokeWidth` | `number` | `0` | Optional cell border outline width in pixels. |
|
|
525
|
+
| `showValues` | `boolean` | `false` | Whether to render numeric text labels inside cells with high-contrast text color calculation. |
|
|
526
|
+
| `xCategories` | `readonly unknown[]` | `undefined` | Explicit X-axis category order. |
|
|
527
|
+
| `yCategories` | `readonly unknown[]` | `undefined` | Explicit Y-axis category order. |
|
|
528
|
+
| `name` | `string` | `"Heatmap"` | Series name for tooltips, legends, and accessibility. |
|
|
529
|
+
| `visible` | `model(boolean)` | `true` | Two-way bindable series visibility. |
|
|
530
|
+
| `valueFormatter` | `ChartValueFormatter` | `undefined` | Formatter function for cell numeric values. |
|
|
531
|
+
|
|
532
|
+
---
|
|
533
|
+
|
|
534
|
+
## Export & Download API
|
|
535
|
+
|
|
536
|
+
The chart component provides programmatic methods to export charts into high-fidelity standalone SVG vector documents, crisp PNG raster images, and formatted PDF documents.
|
|
537
|
+
|
|
538
|
+
### Public Component Methods
|
|
539
|
+
|
|
540
|
+
```typescript
|
|
541
|
+
// Export as a binary Blob
|
|
542
|
+
const result: ChartExportResult = await chart.exportChart(options);
|
|
543
|
+
|
|
544
|
+
// Export and trigger a browser file download
|
|
545
|
+
const result: ChartExportResult = await chart.downloadChart(options);
|
|
546
|
+
```
|
|
547
|
+
|
|
548
|
+
### Export Formats & Behavior
|
|
549
|
+
|
|
550
|
+
#### Standalone SVG Vector (`format: "svg"`)
|
|
551
|
+
|
|
552
|
+
Generates a standalone, self-contained SVG document with resolved styling, embedded raster islands for custom templates and complex transformed DOM labels, accessible SVG `<title>` and `<desc>` metadata with ARIA attributes, and zero external resource dependencies.
|
|
553
|
+
|
|
554
|
+
```typescript
|
|
555
|
+
const result = await chart.exportChart({
|
|
556
|
+
format: "svg",
|
|
557
|
+
accessibility: true,
|
|
558
|
+
background: "auto"
|
|
559
|
+
});
|
|
560
|
+
```
|
|
561
|
+
|
|
562
|
+
#### High-Resolution PNG (`format: "png"`)
|
|
563
|
+
|
|
564
|
+
Rasterizes chart graphics and DOM overlay layers to a PNG blob at the desired pixel density. Supports `pixelRatio` between `0.25` and `8.0` (defaults to `2`). Values outside this range throw `ChartExportError("invalid-size")`.
|
|
565
|
+
|
|
566
|
+
```typescript
|
|
567
|
+
await chart.downloadChart({
|
|
568
|
+
format: "png",
|
|
569
|
+
fileName: "revenue-report",
|
|
570
|
+
pixelRatio: 2,
|
|
571
|
+
background: "#ffffff"
|
|
572
|
+
});
|
|
573
|
+
```
|
|
574
|
+
|
|
575
|
+
#### Document PDF (`format: "pdf"`)
|
|
576
|
+
|
|
577
|
+
Generates a PDF document fitted to standard paper sizes (`"a4"`, `"letter"`), custom dimensions, or exact chart boundaries (`"chart"`).
|
|
578
|
+
|
|
579
|
+
- **Standard 14 Vector Fonts:** Vector conversion supports built-in PDF standard font families (`Helvetica`, `Times`, `Courier`) with standard ASCII characters (`0x20..0x7E`). Font safety is resolved from the _effective_ font of each text node, including fonts inherited from ancestor SVG elements and inline `font`/`font-family` declarations; uncertified inherited fonts trigger raster fallback exactly like direct ones. Text with no font declaration anywhere is treated as the converter default (Helvetica).
|
|
580
|
+
- **Auto Mode (`mode: "auto"`):** Automatically converts certified standard vector graphics and fonts to vector PDF; safely falls back to high-resolution raster PDF when custom web fonts, non-ASCII Unicode glyphs, or complex SVG constructs are detected.
|
|
581
|
+
- **Strict Vector Mode (`mode: "vector"`):** Enforces direct vector conversion; throws `ChartExportError("pdf-vector-unsupported")` if custom fonts, uncertified glyphs, or unsupported SVG features are present.
|
|
582
|
+
- **Raster Mode (`mode: "raster"`):** Directly generates a raster PDF without attempting vector conversion.
|
|
583
|
+
|
|
584
|
+
```typescript
|
|
585
|
+
await chart.downloadChart({
|
|
586
|
+
format: "pdf",
|
|
587
|
+
fileName: "quarterly-presentation",
|
|
588
|
+
mode: "auto",
|
|
589
|
+
page: {
|
|
590
|
+
size: "a4",
|
|
591
|
+
orientation: "landscape",
|
|
592
|
+
margin: 24
|
|
593
|
+
}
|
|
594
|
+
});
|
|
595
|
+
```
|
|
596
|
+
|
|
597
|
+
### Export Options Reference
|
|
598
|
+
|
|
599
|
+
| Option | Type | Default | Description |
|
|
600
|
+
| :----------------------- | :------------------------------------------------- | :----------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
|
|
601
|
+
| `format` | `"svg" \| "png" \| "pdf"` | _Required_ | Target export format. |
|
|
602
|
+
| `fileName` | `string` | `chart.title` or `"chart"` | Filename for `downloadChart()` (sanitized automatically). |
|
|
603
|
+
| `width` | `number` | Chart width | Output logical width in CSS pixels. When aspect ratio differs from source, chart content is centered using contain scaling. |
|
|
604
|
+
| `height` | `number` | Chart height | Output logical height in CSS pixels. |
|
|
605
|
+
| `background` | `"auto" \| "transparent" \| string` | `"auto"` | Background fill policy or concrete CSS color. CSS-wide keywords (`inherit`, `initial`, `unset`) are rejected. |
|
|
606
|
+
| `pixelRatio` | `number` | `2` | Raster scaling density (accepted range `0.25` to `8.0`) for PNG export. |
|
|
607
|
+
| `accessibility` | `boolean` | `true` | Embeds accessible `<title>`, `<desc>`, and ARIA attributes in SVG. |
|
|
608
|
+
| `mode` | `"auto" \| "vector" \| "raster"` | `"auto"` | PDF rendering path (auto vector with raster fallback, strict vector, or raster). |
|
|
609
|
+
| `page.size` | `"chart" \| "a4" \| "letter" \| { width, height }` | `"chart"` | PDF page sizing in points (1 CSS px = 0.75 pt). |
|
|
610
|
+
| `page.orientation` | `"auto" \| "portrait" \| "landscape"` | `"auto"` | PDF page orientation. |
|
|
611
|
+
| `page.margin` | `number \| { top, right, bottom, left }` | `0` (chart) / `24` (A4/Letter) | PDF page margins in points. |
|
|
612
|
+
| `presentation.selection` | `boolean` | `true` | Include persistent selection mark styling. |
|
|
613
|
+
| `presentation.crosshair` | `boolean` | `false` | Include active crosshair lines and axis badges. |
|
|
614
|
+
| `presentation.brush` | `boolean` | `false` | Include active brush marquee rectangle. |
|
|
615
|
+
| `signal` | `AbortSignal` | `undefined` | AbortSignal to cancel in-flight export operations. |
|
|
616
|
+
|
|
617
|
+
### Technical Considerations & Limitations
|
|
618
|
+
|
|
619
|
+
- **Browser-only:** Export operations run entirely in the browser and require `document`, `fetch`, canvas, and image decoding support. Server-side invocation throws `ChartExportError("unsupported-environment")`.
|
|
620
|
+
- **Snapshot Semantics:** Export captures a frozen semantic and visual snapshot synchronously at the `exportChart()` call boundary. After that boundary, live chart data, theme, and signal changes do not affect an in-flight export. Supported external resources referenced by the snapshot are then captured into export-owned embedded representations before rasterization begins. Export uses the committed scene; output dimensions and pixel ratio do not trigger a different semantic sample or a new density projection.
|
|
621
|
+
- **Custom Templates & Transformed DOM:** Custom Angular template content (e.g. `monaChartLegendItemTemplate`, `monaChartCenterTemplate`) and complex CSS transformed DOM labels (e.g. rotated axis labels) are captured as isolated raster islands and embedded as data URIs within SVG and hybrid PDF artifacts.
|
|
622
|
+
- **Resource Capture & CORS:** External template images (`<img>`, `input[type="image"]`, SVG `<image>`, CSS `background`/`background-image`/`border-image(-source)`/`list-style(-image)`) are fetched with bounded streaming reads, validated as decodable PNG/JPEG/WebP bytes, and rewritten to embedded data URLs before rasterization. Cross-origin images must be CORS-accessible. A response that is empty, non-image, oversized, or undecodable fails the export explicitly instead of silently producing missing content.
|
|
623
|
+
- **True Decode Guarantee:** Every accepted raster payload passes a real browser image decode (`createImageBitmap`, or an event-driven object-URL `HTMLImageElement` decode when unavailable). Header/magic-byte checks are only a fast pre-gate; malformed JPEG/WebP/PNG bodies that carry plausible headers are still rejected. Environments without any image decoding capability fail explicitly.
|
|
624
|
+
- **Embedded Data URI Policy:** Raster data URIs must be base64-encoded PNG/JPEG/WebP with magic bytes matching their declared media type; percent-encoded binary payloads are rejected.
|
|
625
|
+
- **Responsive Images:** For `<img srcset>` and `<picture><source>` structures, the currently displayed image (`currentSrc`) is captured and responsive reselection is disabled in the exported copy; the artifact always shows the image selected at export time.
|
|
626
|
+
- **Embedded SVG Images:** SVG resources embedded via data URI are rejected for export because nested SVG documents can reference additional external resources.
|
|
627
|
+
- **Template Font Readiness:** After the document font-loading barrier, a custom template whose entire font stack consists of registered web fonts that failed to load fails the export explicitly rather than silently substituting fallback typography. Stacks that resolve to any loaded web font or system font export exactly what the live chart displays.
|
|
628
|
+
- **Resource & Raster Safety Limits:** Export work is subject to internal safety limits covering per-resource and transaction-wide byte budgets, decoded image/canvas bitmap dimensions, and aggregate raster-island pixel work per transaction. Decoded dimensions are validated against these limits before any raster backing-store allocation, on every resource capture path. Exceeding any limit fails explicitly with `ChartExportError("too-large")`; quality is never silently reduced to fit.
|
|
629
|
+
- **Concurrent Export Isolation:** Multiple `exportChart()` invocations may overlap freely. Each invocation owns its own snapshot, resource capture, temporary fragment namespace, staging DOM, and abort controller; completing or aborting one export never affects another in-flight export.
|
|
630
|
+
|
|
631
|
+
### Custom Template Support Contract
|
|
632
|
+
|
|
633
|
+
Custom templates must be fully freezable: every visual feature is either supported or explicitly rejected with `ChartExportError("unsupported-template")`. An export never succeeds with silently omitted visual content.
|
|
634
|
+
|
|
635
|
+
**Supported:**
|
|
636
|
+
|
|
637
|
+
- Light DOM elements, plain text, inline styles, and element/class-scoped CSS that resolves to computed styles
|
|
638
|
+
- `<img>` (including `srcset`/`<picture>`, frozen to the selected source), `<input type="image">` sources, CSS background/border/list images, SVG `<image>` with external/data raster sources
|
|
639
|
+
- Canvas elements (must not be cross-origin tainted; backing stores are subject to internal bitmap budgets)
|
|
640
|
+
- Inset-only box shadows contained within the template bounds
|
|
641
|
+
- 2D affine CSS transforms (rotation, scale, skew, 2D matrix) via raster islands
|
|
642
|
+
- Contained light-DOM descendants
|
|
643
|
+
- Island-local SVG fragment references after automatic ID isolation: `<use href="#id">`, `textPath[href="#id"]`, gradient/pattern inheritance `href="#id"`, and presentation-attribute/CSS `url(#id)` references are all namespaced per export transaction and island before staging so they cannot resolve to same-ID elements in the live page or in another concurrently staged export. Referenced targets must exist inside the same frozen island and be recursively resource-safe.
|
|
644
|
+
|
|
645
|
+
**Rejected:**
|
|
646
|
+
|
|
647
|
+
- Visible `::before` / `::after` pseudo-element content or painted pseudo styling (borders, outlines, shadows)
|
|
648
|
+
- `<style>` elements, external stylesheet `<link rel="stylesheet">`, and `<script>` elements inside the template
|
|
649
|
+
- Active SVG timing content (`<animate>`, `<animateTransform>`, `<animateMotion>`, `<set>`, animation `<mpath>`): SMIL is an independent animation system the CSS-animation freezer cannot stop, so its presence fails the template instead of risking nondeterministic snapshots
|
|
650
|
+
- CSS `mask-image`, `mask`, `backdrop-filter`, CSS `filter`, and non-inset `box-shadow`
|
|
651
|
+
- CSS `outline` and `text-shadow`
|
|
652
|
+
- Open/detectable Shadow DOM in custom templates. Closed Shadow-DOM-backed custom elements cannot be detected from outside the element and are outside the first-release template export contract; they must not be relied on for export fidelity.
|
|
653
|
+
- 3D CSS transforms (`matrix3d`, `perspective`, `rotate3d`, etc.) and unparseable/unknown transform syntax
|
|
654
|
+
- Descendants with layout overflow outside the template bounds
|
|
655
|
+
- `video`, `audio`, `iframe`, `object`, `embed`, SVG `<feImage>`
|
|
656
|
+
- External/unresolvable SVG fragment references: external `<use>` documents, external gradient/pattern inheritance targets, `textPath` targets outside the frozen island, and any unrecognized visual `href`/`src`/`url()` surface. Ordinary navigation links (`<a href>`) are inert for rasterization and neither captured nor followed.
|
|
657
|
+
|
|
658
|
+
Clipping applied by ancestors _outside_ the captured template node is intentionally represented by the plot-area clip rectangle; arbitrary nested consumer clipping cannot be reproduced and should wrap the chart accordingly.
|
|
659
|
+
|
|
660
|
+
### PDF Raster Fidelity
|
|
661
|
+
|
|
662
|
+
Raster PDF output (both explicit `mode: "raster"` and automatic fallback) chooses its internal pixel density from the final PDF page occupancy, including paper-page fitting and upscaling, so enlarged pages do not blur a low-density bitmap. Outputs whose required pixel dimensions exceed browser allocation safety limits throw `ChartExportError("too-large")` instead of silently reducing fidelity.
|