frappe-ui 1.0.2 → 1.1.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/experimental/Calendar/calendarUtils.ts +33 -21
- package/experimental/MultiEmailInput/MultiEmailInput.vue +64 -12
- package/experimental/MultiEmailInput/types.ts +12 -3
- package/experimental/Stepper/StepIndicator.vue +129 -0
- package/experimental/Stepper/Stepper.api.md +117 -0
- package/experimental/Stepper/Stepper.md +95 -0
- package/experimental/Stepper/Stepper.vue +82 -0
- package/experimental/Stepper/StepperHorizontal.vue +93 -0
- package/experimental/Stepper/StepperVertical.vue +291 -0
- package/experimental/Stepper/index.ts +11 -0
- package/experimental/Stepper/resolve.ts +87 -0
- package/experimental/Stepper/types.ts +89 -0
- package/experimental.ts +2 -0
- package/package.json +1 -1
- package/src/charts/CalendarHeatmapChart.vue +353 -0
- package/src/charts/DonutChart.vue +34 -58
- package/src/charts/HeatmapChart.vue +26 -64
- package/src/charts/NumberCard.vue +62 -7
- package/src/charts/PercentageBarChart.vue +243 -0
- package/src/charts/SankeyChart.vue +14 -11
- package/src/charts/ScatterChart.vue +24 -20
- package/src/charts/axisChartCommon.ts +182 -18
- package/src/charts/axisFormat.ts +8 -3
- package/src/charts/calendarHeatmapOptions.ts +604 -0
- package/src/charts/colorMath.ts +26 -0
- package/src/charts/components/ChartContainer.vue +63 -53
- package/src/charts/components/ChartLegend.vue +216 -24
- package/src/charts/components/ChartScale.vue +85 -0
- package/src/charts/core/dataLabelFit.ts +45 -6
- package/src/charts/core/useAxisChart.ts +36 -19
- package/src/charts/core/useChart.ts +6 -1
- package/src/charts/core/usePlotKeyboard.ts +13 -2
- package/src/charts/docs/BarChart.md +11 -3
- package/src/charts/docs/CalendarHeatmapChart.api.md +165 -0
- package/src/charts/docs/CalendarHeatmapChart.md +33 -0
- package/src/charts/docs/ChartContainer.api.md +6 -0
- package/src/charts/docs/ChartLegend.api.md +1 -1
- package/src/charts/docs/ChartLegend.md +25 -3
- package/src/charts/docs/DonutChart.api.md +12 -0
- package/src/charts/docs/DonutChart.md +17 -0
- package/src/charts/docs/HeatmapChart.api.md +1 -1
- package/src/charts/docs/LineChart.md +5 -3
- package/src/charts/docs/NumberCard.api.md +6 -0
- package/src/charts/docs/NumberCard.md +6 -0
- package/src/charts/docs/Overview.md +13 -6
- package/src/charts/docs/PercentageBarChart.api.md +148 -0
- package/src/charts/docs/PercentageBarChart.md +42 -0
- package/src/charts/docs/ScatterChart.md +2 -3
- package/src/charts/donutChartOptions.ts +22 -130
- package/src/charts/format.ts +4 -1
- package/src/charts/heatmapOptions.ts +17 -12
- package/src/charts/hiddenSeries.ts +8 -3
- package/src/charts/index.ts +12 -0
- package/src/charts/legendOverflow.ts +40 -0
- package/src/charts/numberCardFormat.ts +19 -13
- package/src/charts/referenceLines.ts +2 -1
- package/src/charts/scatterOptions.ts +16 -3
- package/src/charts/seriesData.ts +8 -3
- package/src/charts/slices.ts +228 -0
- package/src/charts/tokens.ts +99 -0
- package/src/charts/types.ts +318 -9
- package/src/components/Avatar/Avatar.md +27 -2
- package/src/components/Avatar/Avatar.vue +29 -12
- package/src/components/Combobox/Combobox.vue +9 -2
- package/src/components/Combobox/ComboboxResults.vue +6 -1
- package/src/components/Combobox/utils.ts +2 -1
- package/src/components/Dialog/Dialog.md +3 -1
- package/src/components/Duration/Duration.api.md +16 -3
- package/src/components/Duration/Duration.md +21 -0
- package/src/components/Duration/Duration.vue +29 -8
- package/src/components/Duration/duration.ts +105 -44
- package/src/components/Duration/index.ts +1 -0
- package/src/components/Duration/types.ts +30 -1
- package/src/components/Menu/utils.ts +3 -2
- package/src/components/MultiSelect/MultiSelect.api.md +5 -0
- package/src/components/MultiSelect/MultiSelect.vue +34 -0
- package/src/components/MultiSelect/MultiSelectResults.vue +3 -4
- package/src/components/MultiSelect/types.ts +6 -0
- package/src/components/Select/Select.vue +4 -4
- package/src/components/Select/utils.ts +1 -0
- package/src/components/Switch/Switch.vue +3 -3
- package/src/components/shared/selection/utils.ts +8 -1
- package/src/data-fetching/useCall/useCall.ts +25 -26
- package/src/data-fetching/useFrappeFetch.ts +48 -2
- package/src/data-fetching/useList/useList.ts +11 -3
- package/src/data-fetching/utils.ts +15 -1
- package/src/molecules/editor/components/MediaNodeView.vue +10 -1
- package/src/molecules/editor/components/MediaResizeGuide.vue +71 -0
- package/src/molecules/editor/components/media-node-view-utils.ts +7 -0
- package/src/molecules/editor/composables/useNodeViewResize.ts +142 -10
- package/src/molecules/editor/extensions/iframe/IframeNodeView.vue +3 -1
- package/src/molecules/editor/useEditor.ts +12 -6
- package/src/utils/dialog.ts +37 -14
- package/tailwind/content.js +1 -0
- package/vite/README.md +5 -3
- package/vite/codeLanguages.js +41 -17
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
import { computed, reactive, ref, watch, type Ref } from 'vue'
|
|
2
2
|
import type { EChartsCoreOption } from 'echarts/core'
|
|
3
|
-
import {
|
|
3
|
+
import {
|
|
4
|
+
dataLabelOverflow,
|
|
5
|
+
nextAxisTick,
|
|
6
|
+
referenceLabelOverflow,
|
|
7
|
+
} from './dataLabelFit'
|
|
4
8
|
import { useChart } from './useChart'
|
|
5
9
|
import { usePlotKeyboard } from './usePlotKeyboard'
|
|
6
10
|
import { useTooltipDismiss } from './useTooltipDismiss'
|
|
@@ -17,11 +21,12 @@ import { pruneHiddenSeries, toggleHiddenSeries } from '../hiddenSeries'
|
|
|
17
21
|
import { buildTooltipItems } from '../tooltipItems'
|
|
18
22
|
import {
|
|
19
23
|
seriesLabel,
|
|
24
|
+
seriesWeights,
|
|
20
25
|
type AxisChartFormatters,
|
|
21
26
|
type ResolvedTooltipColumn,
|
|
22
27
|
} from '../seriesData'
|
|
23
|
-
import { formatAxisValue,
|
|
24
|
-
import { useChartTokens } from '../tokens'
|
|
28
|
+
import { formatAxisValue, formatValue } from '../format'
|
|
29
|
+
import { useChartTokens, useResolvedConfig } from '../tokens'
|
|
25
30
|
import { documentDir, markName, plotReading } from '../utils'
|
|
26
31
|
import type {
|
|
27
32
|
AxisChartConfig,
|
|
@@ -70,7 +75,7 @@ export function useAxisChart<C extends AxisChartConfig>(
|
|
|
70
75
|
const plotEl = ref<HTMLElement>()
|
|
71
76
|
const hiddenSeries = args.hiddenSeries ?? ref<string[]>([])
|
|
72
77
|
|
|
73
|
-
const config =
|
|
78
|
+
const config = useResolvedConfig(args.config, plotEl)
|
|
74
79
|
const format = computed<AxisChartFormatters>(() => args.format?.() ?? {})
|
|
75
80
|
const horizontal = computed(() => Boolean(args.horizontal?.()))
|
|
76
81
|
const stackShares = computed(() => args.stackShares?.())
|
|
@@ -106,15 +111,11 @@ export function useAxisChart<C extends AxisChartConfig>(
|
|
|
106
111
|
const axisTitlePlacement = computed<AxisTitlePlacement>(() =>
|
|
107
112
|
horizontal.value ? 'bottom' : 'top',
|
|
108
113
|
)
|
|
109
|
-
const yAxisTitle = computed(() =>
|
|
110
|
-
config.value.yAxis?.title
|
|
111
|
-
? formatLabel(config.value.yAxis.title)
|
|
112
|
-
: undefined,
|
|
113
|
-
)
|
|
114
|
+
const yAxisTitle = computed(() => config.value.yAxis?.title || undefined)
|
|
114
115
|
const y2AxisTitle = computed(() =>
|
|
115
116
|
config.value.y2Axis?.title &&
|
|
116
117
|
hasSecondaryValueAxis(config.value, horizontal.value)
|
|
117
|
-
?
|
|
118
|
+
? config.value.y2Axis.title
|
|
118
119
|
: undefined,
|
|
119
120
|
)
|
|
120
121
|
|
|
@@ -174,9 +175,10 @@ export function useAxisChart<C extends AxisChartConfig>(
|
|
|
174
175
|
let raisedFor: EChartsCoreOption | undefined
|
|
175
176
|
|
|
176
177
|
/**
|
|
177
|
-
* A data label at the top of the scale reaches
|
|
178
|
-
* goes up one tick to make room for it, so the
|
|
179
|
-
* card whatever the numbers are. An axis end the
|
|
178
|
+
* A data label or a reference-line label at the top of the scale reaches
|
|
179
|
+
* past the plot. The value axis goes up one tick to make room for it, so the
|
|
180
|
+
* plot keeps its place in the card whatever the numbers are. An axis end the
|
|
181
|
+
* caller fixed is theirs.
|
|
180
182
|
*/
|
|
181
183
|
function fitLabels() {
|
|
182
184
|
const instance = chart.value
|
|
@@ -192,21 +194,36 @@ export function useAxisChart<C extends AxisChartConfig>(
|
|
|
192
194
|
: 'right'
|
|
193
195
|
: 'top'
|
|
194
196
|
if (typeof option.grid[side] !== 'number') return
|
|
195
|
-
const overflow =
|
|
196
|
-
|
|
197
|
+
const overflow = Math.max(
|
|
198
|
+
dataLabelOverflow(instance, side, option.grid[side]) ?? -Infinity,
|
|
199
|
+
referenceLabelOverflow(instance, side, option.grid[side]) ?? -Infinity,
|
|
200
|
+
)
|
|
201
|
+
if (overflow <= 0) return
|
|
197
202
|
|
|
198
|
-
const
|
|
199
|
-
if (
|
|
203
|
+
const tick = nextAxisTick(instance, valueAxis)
|
|
204
|
+
if (tick === null) return
|
|
200
205
|
raisedFor = option
|
|
201
|
-
instance.setOption({ [valueAxis]: [
|
|
206
|
+
instance.setOption({ [valueAxis]: [tick] })
|
|
202
207
|
}
|
|
203
208
|
|
|
209
|
+
// Apart from the legend entries, which rebuild on every toggle: hiding a
|
|
210
|
+
// series does not change its weight.
|
|
211
|
+
const weights = computed(() =>
|
|
212
|
+
seriesWeights(
|
|
213
|
+
rows.value,
|
|
214
|
+
config.value.series.map((series) => series.name),
|
|
215
|
+
),
|
|
216
|
+
)
|
|
217
|
+
|
|
218
|
+
// No number is printed beside an axis series: a sum is wrong for a rate or
|
|
219
|
+
// an average, and the chart cannot tell which one it was handed.
|
|
204
220
|
const legendItems = computed<ChartLegendItem[]>(() =>
|
|
205
221
|
config.value.series.map((series) => ({
|
|
206
222
|
name: series.name,
|
|
207
223
|
label: seriesLabel(series),
|
|
208
224
|
color: seriesColors.value[series.name],
|
|
209
225
|
hidden: hiddenSeries.value.includes(series.name),
|
|
226
|
+
weight: weights.value[series.name],
|
|
210
227
|
})),
|
|
211
228
|
)
|
|
212
229
|
|
|
@@ -219,7 +236,7 @@ export function useAxisChart<C extends AxisChartConfig>(
|
|
|
219
236
|
hiddenSeries.value = toggleHiddenSeries(
|
|
220
237
|
hiddenSeries.value,
|
|
221
238
|
name,
|
|
222
|
-
|
|
239
|
+
visibleSeries.value.map((series) => series.name),
|
|
223
240
|
)
|
|
224
241
|
}
|
|
225
242
|
|
|
@@ -50,6 +50,8 @@ export type UseChartReturn = {
|
|
|
50
50
|
resize: () => void
|
|
51
51
|
/** Measured plot width, 0 until the container has one. Follows resizes. */
|
|
52
52
|
width: Ref<number>
|
|
53
|
+
/** Measured plot height, as `width`. */
|
|
54
|
+
height: Ref<number>
|
|
53
55
|
}
|
|
54
56
|
|
|
55
57
|
const RESIZE_DEBOUNCE_MS = 100
|
|
@@ -131,12 +133,14 @@ export function useChart({
|
|
|
131
133
|
})
|
|
132
134
|
|
|
133
135
|
const width = ref(0)
|
|
136
|
+
const height = ref(0)
|
|
134
137
|
|
|
135
138
|
// Sizes decided in pixels — the cap on a horizontal chart's label column —
|
|
136
139
|
// are built into the option, so a resize has to re-run the builder as well as
|
|
137
140
|
// re-lay the plot. Publishing the width here is what makes it re-run.
|
|
138
141
|
const resize = () => {
|
|
139
142
|
width.value = container.value?.clientWidth ?? 0
|
|
143
|
+
height.value = container.value?.clientHeight ?? 0
|
|
140
144
|
// The plot slides to its new size, unless the reader has asked for less
|
|
141
145
|
// movement — a whole chart re-laying itself is a large piece of motion.
|
|
142
146
|
chart.value?.resize({
|
|
@@ -168,6 +172,7 @@ export function useChart({
|
|
|
168
172
|
const instance = init(el, undefined, { renderer: 'svg' })
|
|
169
173
|
chart.value = instance
|
|
170
174
|
width.value = el.clientWidth
|
|
175
|
+
height.value = el.clientHeight
|
|
171
176
|
|
|
172
177
|
for (const [name, handler] of Object.entries(events ?? {})) {
|
|
173
178
|
instance.on(name, handler)
|
|
@@ -202,5 +207,5 @@ export function useChart({
|
|
|
202
207
|
const dispatch = (payload: Record<string, any>) =>
|
|
203
208
|
chart.value?.dispatchAction(payload as any)
|
|
204
209
|
|
|
205
|
-
return { chart, dispatch, resize, width }
|
|
210
|
+
return { chart, dispatch, resize, width, height }
|
|
206
211
|
}
|
|
@@ -41,6 +41,11 @@ export type PlotKeyboardArgs<T> = {
|
|
|
41
41
|
* others, so a plot with one dimension answers to all four keys.
|
|
42
42
|
*/
|
|
43
43
|
cross?: (delta: number) => void
|
|
44
|
+
/**
|
|
45
|
+
* Left and right, where one press is more than one mark: a calendar steps a
|
|
46
|
+
* week, and walks its days with up and down. Left out, they step one mark.
|
|
47
|
+
*/
|
|
48
|
+
along?: (delta: number) => void
|
|
44
49
|
}
|
|
45
50
|
|
|
46
51
|
export type PlotKeyboardReturn = {
|
|
@@ -135,6 +140,12 @@ export function usePlotKeyboard<T>(
|
|
|
135
140
|
args.cross(delta)
|
|
136
141
|
}
|
|
137
142
|
|
|
143
|
+
/** Left and right, which step from no cursor as `cross` does. */
|
|
144
|
+
function along(delta: number) {
|
|
145
|
+
if (!args.along || index.value === null) return step(delta)
|
|
146
|
+
args.along(delta)
|
|
147
|
+
}
|
|
148
|
+
|
|
138
149
|
function refresh() {
|
|
139
150
|
if (index.value === null) return
|
|
140
151
|
if (!count.value) return leave()
|
|
@@ -166,10 +177,10 @@ export function usePlotKeyboard<T>(
|
|
|
166
177
|
|
|
167
178
|
switch (event.key) {
|
|
168
179
|
case 'ArrowRight':
|
|
169
|
-
|
|
180
|
+
along(1)
|
|
170
181
|
break
|
|
171
182
|
case 'ArrowLeft':
|
|
172
|
-
|
|
183
|
+
along(-1)
|
|
173
184
|
break
|
|
174
185
|
case 'ArrowDown':
|
|
175
186
|
cross(1)
|
|
@@ -67,6 +67,10 @@ flat, because flat text is easier to read. Crowded slots tilt, where a flat
|
|
|
67
67
|
label would shrink to a few letters. All labels on the axis use the same layout,
|
|
68
68
|
because labels at two angles look like two axes.
|
|
69
69
|
|
|
70
|
+
A tilt is used only when it can label every category with space between the labels. When the slots are narrower than that, labels must be dropped in either layout, so the axis stays flat and labels every few categories instead, such as every seventh day of a month. The labels are spread evenly from the first category to the last, and each label is shown whole up to the length a tilted label can show.
|
|
71
|
+
|
|
72
|
+
A label from `xAxis.format` is measured and truncated the same way, in the middle.
|
|
73
|
+
|
|
70
74
|
There is no angle prop and no truncation length. The right angle changes with
|
|
71
75
|
the chart width, and the chart already knows the width and has measured the
|
|
72
76
|
text. A `horizontal` chart never tilts its labels: they are already one per line
|
|
@@ -74,6 +78,10 @@ down the side, so they are truncated to fit that column. A time axis never tilts
|
|
|
74
78
|
either. It picks its own ticks, and uses a larger interval instead of crowding
|
|
75
79
|
them.
|
|
76
80
|
|
|
81
|
+
## Counts
|
|
82
|
+
|
|
83
|
+
When every value on a value axis is a whole number, its ticks are whole numbers too, so a count of 2 never gets a tick at 0.5. This applies to `y`, `y2` and the value axis of a `horizontal` chart, each decided from its own series. Set `yAxis.integer` (or `y2Axis.integer`) to `true` or `false` to override it.
|
|
84
|
+
|
|
77
85
|
## A line among the bars
|
|
78
86
|
|
|
79
87
|
`seriesConfig[key].type` sets how one series draws: `'bar'`, `'line'` or
|
|
@@ -110,9 +118,9 @@ label, and its two sides are left and right.
|
|
|
110
118
|
|
|
111
119
|
`axis` sets which axis `value` belongs to: `'y'` (the default) or `'y2'` for a
|
|
112
120
|
horizontal line at a value, `'x'` for a vertical line at a category or date.
|
|
113
|
-
`horizontal` swaps the two axes and the lines follow.
|
|
114
|
-
|
|
115
|
-
|
|
121
|
+
`horizontal` swaps the two axes and the lines follow. The value axis stretches
|
|
122
|
+
to reach every line, so a target above the data stays in view, and goes up a
|
|
123
|
+
tick when a line at its top end leaves no room for the label.
|
|
116
124
|
|
|
117
125
|
## Context in the tooltip
|
|
118
126
|
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
<!-- Auto Generated by scripts/propsgen.ts -->
|
|
2
|
+
<script setup>
|
|
3
|
+
import PropsTable from '@/components/Docs/PropsTable.vue'
|
|
4
|
+
import SlotsTable from '@/components/Docs/SlotsTable.vue'
|
|
5
|
+
import EmitsTable from '@/components/Docs/EmitsTable.vue'
|
|
6
|
+
import ExposedTable from '@/components/Docs/ExposedTable.vue'
|
|
7
|
+
|
|
8
|
+
const propsData = [
|
|
9
|
+
{
|
|
10
|
+
name: 'title',
|
|
11
|
+
description: 'Heads the card. Left out, the chart draws no header row at all.',
|
|
12
|
+
required: false,
|
|
13
|
+
type: 'string'
|
|
14
|
+
},
|
|
15
|
+
{
|
|
16
|
+
name: 'subtitle',
|
|
17
|
+
description: 'A second line under the title, e.g. the period the numbers cover.',
|
|
18
|
+
required: false,
|
|
19
|
+
type: 'string'
|
|
20
|
+
},
|
|
21
|
+
{
|
|
22
|
+
name: 'dir',
|
|
23
|
+
description: 'Forces layout direction; defaults to document.documentElement.dir',
|
|
24
|
+
required: false,
|
|
25
|
+
type: 'ChartDir'
|
|
26
|
+
},
|
|
27
|
+
{
|
|
28
|
+
name: 'loading',
|
|
29
|
+
description: 'Draws the placeholder in place of the plot, for data still on its way.',
|
|
30
|
+
required: false,
|
|
31
|
+
type: 'boolean'
|
|
32
|
+
},
|
|
33
|
+
{
|
|
34
|
+
name: 'error',
|
|
35
|
+
description: 'Puts the chart in its error state and prints this message under it. Data\nthe chart cannot draw shows the empty state, not this one.',
|
|
36
|
+
required: false,
|
|
37
|
+
type: 'string | null'
|
|
38
|
+
},
|
|
39
|
+
{
|
|
40
|
+
name: 'data',
|
|
41
|
+
description: 'The rows to plot, one per day. Of two on the same day, the later one is drawn.',
|
|
42
|
+
required: true,
|
|
43
|
+
type: 'Record<string, any>[]'
|
|
44
|
+
},
|
|
45
|
+
{
|
|
46
|
+
name: 'date',
|
|
47
|
+
description: 'Row key holding the day: a `Date`, or an ISO string such as `2024-03-01`.\nA time or offset after the date is ignored.',
|
|
48
|
+
required: true,
|
|
49
|
+
type: 'string'
|
|
50
|
+
},
|
|
51
|
+
{
|
|
52
|
+
name: 'value',
|
|
53
|
+
description: 'Row key holding the magnitude the day is colored by.',
|
|
54
|
+
required: true,
|
|
55
|
+
type: 'string'
|
|
56
|
+
},
|
|
57
|
+
{
|
|
58
|
+
name: 'start',
|
|
59
|
+
description: 'First day drawn, as a `Date` or an ISO string. Defaults to the first of the\nmonth the data starts in. Given with `end`, the range is drawn even with no\ndata in it.',
|
|
60
|
+
required: false,
|
|
61
|
+
type: 'string | Date'
|
|
62
|
+
},
|
|
63
|
+
{
|
|
64
|
+
name: 'end',
|
|
65
|
+
description: 'Last day drawn. Defaults to the last of the month the data ends in.',
|
|
66
|
+
required: false,
|
|
67
|
+
type: 'string | Date'
|
|
68
|
+
},
|
|
69
|
+
{
|
|
70
|
+
name: 'weekStart',
|
|
71
|
+
description: 'The weekday at the top of each column. Defaults to the week start of the\ndayjs locale, and to `\'sunday\'` when the locale names none.',
|
|
72
|
+
required: false,
|
|
73
|
+
type: 'CalendarHeatmapWeekStart'
|
|
74
|
+
},
|
|
75
|
+
{
|
|
76
|
+
name: 'min',
|
|
77
|
+
description: 'Bottom of the color scale. Defaults to 0 when no day is negative, else to\nthe smallest day in the range.',
|
|
78
|
+
required: false,
|
|
79
|
+
type: 'number'
|
|
80
|
+
},
|
|
81
|
+
{
|
|
82
|
+
name: 'max',
|
|
83
|
+
description: 'Top of the color scale. Defaults to the largest day in the range. Days\nabove it draw in the deepest color, and the scale reads `≥ max`.',
|
|
84
|
+
required: false,
|
|
85
|
+
type: 'number'
|
|
86
|
+
},
|
|
87
|
+
{
|
|
88
|
+
name: 'format',
|
|
89
|
+
description: 'Prints every number the calendar shows: the scale ends and the tooltip.',
|
|
90
|
+
required: false,
|
|
91
|
+
type: 'ChartValueFormatter'
|
|
92
|
+
},
|
|
93
|
+
{
|
|
94
|
+
name: 'palette',
|
|
95
|
+
description: 'Ramp days are colored from. Defaults to `\'sequential\'`; `\'diverging\'` is\nfor signed data and centers on zero.',
|
|
96
|
+
required: false,
|
|
97
|
+
type: 'HeatmapPalette'
|
|
98
|
+
},
|
|
99
|
+
{
|
|
100
|
+
name: 'echartOptions',
|
|
101
|
+
description: 'Escape hatch: deep-merged into the echarts option the props built.',
|
|
102
|
+
required: false,
|
|
103
|
+
type: 'EchartOptionsOverride'
|
|
104
|
+
}
|
|
105
|
+
]
|
|
106
|
+
|
|
107
|
+
const slotsData = [
|
|
108
|
+
{
|
|
109
|
+
name: 'loading',
|
|
110
|
+
description: 'Replaces the whole placeholder, e.g. with a skeleton of the app\'s own.',
|
|
111
|
+
type: 'any'
|
|
112
|
+
},
|
|
113
|
+
{
|
|
114
|
+
name: 'error',
|
|
115
|
+
description: 'Replaces the message, e.g. to put a retry button beside it.',
|
|
116
|
+
type: '{ error?: string | null | undefined; }'
|
|
117
|
+
},
|
|
118
|
+
{
|
|
119
|
+
name: 'empty',
|
|
120
|
+
description: 'Replaces the "no data" line, e.g. with a hint about the filters.',
|
|
121
|
+
type: 'any'
|
|
122
|
+
},
|
|
123
|
+
{
|
|
124
|
+
name: 'actions',
|
|
125
|
+
description: '',
|
|
126
|
+
type: 'any'
|
|
127
|
+
},
|
|
128
|
+
{
|
|
129
|
+
name: 'title-suffix',
|
|
130
|
+
description: 'A mark right after the title, on the same line. The title truncates\naround it and it keeps its width. It renders in the title\'s font size, so\ncontent sized in `em` is smaller on a NumberCard than on a chart.',
|
|
131
|
+
type: 'any'
|
|
132
|
+
},
|
|
133
|
+
{
|
|
134
|
+
name: 'tooltip',
|
|
135
|
+
description: 'Replaces the tooltip body. `items` holds the hovered day alone, and\n`rows` the row behind it. A day with no row reads `No data`, with no row.',
|
|
136
|
+
type: 'ChartTooltipSlotProps'
|
|
137
|
+
}
|
|
138
|
+
]
|
|
139
|
+
|
|
140
|
+
const emitsData = [
|
|
141
|
+
{
|
|
142
|
+
name: 'select',
|
|
143
|
+
description: 'A day with data was selected, by click or by Enter on the keyboard cursor.\nCarries the day, its value and the row behind it.',
|
|
144
|
+
type: '[event: CalendarHeatmapCellEvent]'
|
|
145
|
+
}
|
|
146
|
+
]
|
|
147
|
+
|
|
148
|
+
const exposedData = [
|
|
149
|
+
{
|
|
150
|
+
name: 'chart',
|
|
151
|
+
description: 'The echarts instance, once the plot has a size to initialise into.',
|
|
152
|
+
type: 'EChartsType | undefined'
|
|
153
|
+
}
|
|
154
|
+
]
|
|
155
|
+
</script>
|
|
156
|
+
|
|
157
|
+
## API Reference
|
|
158
|
+
|
|
159
|
+
<PropsTable folder="charts" name="CalendarHeatmapChart" :data="propsData"/>
|
|
160
|
+
|
|
161
|
+
<SlotsTable :data="slotsData"/>
|
|
162
|
+
|
|
163
|
+
<EmitsTable :data="emitsData"/>
|
|
164
|
+
|
|
165
|
+
<ExposedTable :data="exposedData"/>
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# CalendarHeatmapChart
|
|
2
|
+
|
|
3
|
+
Shows a value for each day, with weeks as columns and weekdays as rows.
|
|
4
|
+
|
|
5
|
+
## A year of days
|
|
6
|
+
|
|
7
|
+
`date` and `value` name the day and the value of each row. The day is a `Date` or an ISO string such as `2024-03-01`. A time or offset after the date is ignored. A string is the day it spells, but `new Date('2024-03-01')` is UTC midnight, which west of Greenwich is the day before, so build a `Date` with `new Date(y, m, d)`. Days with no row are drawn empty, so gaps show. `format` formats the numbers in the tooltip and on the scale under the calendar.
|
|
8
|
+
|
|
9
|
+
`weekStart` sets the weekday at the top of each column, `sunday` to `saturday`. Month and weekday names follow the dayjs locale, as the tooltip does, and so does the week start when `weekStart` is not set: Monday in `de` or `en-gb`, Sunday in `en`. An app that stores its own setting, such as Frappe's `first_day_of_the_week`, passes it lowercased.
|
|
10
|
+
|
|
11
|
+
<ComponentPreview name="Charts-CalendarCommits" csr="true" self-layout />
|
|
12
|
+
|
|
13
|
+
## Rows on the same day
|
|
14
|
+
|
|
15
|
+
The chart draws one row per day and does not combine them: of two rows on the same day, the later one is drawn, as on `HeatmapChart`. Sum, count or average per day before the rows reach the chart. `select` reports the day, its value, and the row behind it.
|
|
16
|
+
|
|
17
|
+
## Longer ranges
|
|
18
|
+
|
|
19
|
+
`start` and `end` set the days drawn. Each defaults to the first or last day in the data, rounded out to the whole month. Given both, the chart draws the range even when no row falls in it, because an empty year is a reading too. With no data and no range, it shows the empty state. A range of a year or less draws as one band. A longer range draws in bands of twelve months from its first month, so a fiscal year from April is one band, not two halves. Each band has its years beside it: `2024` for a calendar year, `2023–24` for one that crosses into the next. The cells shrink so every band fits the card. Every band lays out twelve whole months, so the months line up from band to band, and only the days in the range are drawn.
|
|
20
|
+
|
|
21
|
+
<ComponentPreview name="Charts-CalendarYears" csr="true" self-layout />
|
|
22
|
+
|
|
23
|
+
## Scale
|
|
24
|
+
|
|
25
|
+
`palette`, `min` and `max` work as on [HeatmapChart](/docs/charts/heatmapchart). The scale covers the days in the range only. When no day is negative, it starts at 0. The ramp starts a step past its palest color, so every day with a row, 0 included, reads darker than a day without one.
|
|
26
|
+
|
|
27
|
+
One outlier can wash out the rest of the range: a day of 240 among days of 1 to 10 leaves every other day pale. Set `max` to where the ordinary days end. Days above it draw in the deepest color, and the scale reads `≥ 10`, so it does not claim that no day went higher. `min` works the same way at the low end.
|
|
28
|
+
|
|
29
|
+
The calendar always runs left to right, also in RTL. The header, scale and tooltip follow `dir`.
|
|
30
|
+
|
|
31
|
+
The calendar is one tab stop. Up and Down move a day, Left and Right a week, and Home and End go to the first and last day. Days with no row are reached as well and read as no data. Enter selects a day with data.
|
|
32
|
+
|
|
33
|
+
<!-- @include: ./CalendarHeatmapChart.api.md -->
|
|
@@ -53,6 +53,12 @@
|
|
|
53
53
|
required: false,
|
|
54
54
|
type: 'boolean'
|
|
55
55
|
},
|
|
56
|
+
{
|
|
57
|
+
name: 'centered',
|
|
58
|
+
description: 'Centres the plot and its legend in the height the card has to spare, for\na plot as tall as its content. Otherwise the plot takes that height.',
|
|
59
|
+
required: false,
|
|
60
|
+
type: 'boolean'
|
|
61
|
+
},
|
|
56
62
|
{
|
|
57
63
|
name: 'dir',
|
|
58
64
|
description: 'Forces layout direction; defaults to document.documentElement.dir',
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
const propsData = [
|
|
8
8
|
{
|
|
9
9
|
name: 'items',
|
|
10
|
-
description: 'One entry per series, in the order they are drawn.',
|
|
10
|
+
description: 'One entry per series, in the order they are drawn. Entries that do not fit\non one row go behind "+N more", ranked by `weight`.',
|
|
11
11
|
required: true,
|
|
12
12
|
type: 'ChartLegendItem[]'
|
|
13
13
|
}
|
|
@@ -24,14 +24,36 @@ One `ChartLegendItem` per series, in the order the series are drawn:
|
|
|
24
24
|
| `color` | The color the series is drawn in. |
|
|
25
25
|
| `hidden` | Whether the series is hidden. |
|
|
26
26
|
| `hint` | A muted note after the label, e.g. a donut slice's share. |
|
|
27
|
+
| `weight` | What the series is worth across the chart. Ranks the entries that do not fit. |
|
|
28
|
+
| `formattedValue` | A number printed beside the entry in the "+N more" list. |
|
|
27
29
|
|
|
28
30
|
A hidden entry keeps its place in the row and dims: the swatch fades and the
|
|
29
31
|
label turns gray. If the entry left the row, there would be no way to show the
|
|
30
32
|
series again.
|
|
31
33
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
34
|
+
## Many series
|
|
35
|
+
|
|
36
|
+
The legend takes one row at most. When every entry fits, the row shows them in
|
|
37
|
+
the order the series are drawn. When they do not, the row shows the entries
|
|
38
|
+
with the largest `weight`, as many as fit, and then a "+N more" button. A legend
|
|
39
|
+
that wrapped would take the plot's height, and one that scrolled would hide
|
|
40
|
+
series names that most users never scroll to.
|
|
41
|
+
|
|
42
|
+
"+N more" opens a [MultiSelect](/docs/components/multiselect) list of every
|
|
43
|
+
entry, largest `weight` first, with the drawn series checked. Checking or
|
|
44
|
+
unchecking a row emits `change` the way pressing an entry on the row does. The
|
|
45
|
+
arrow keys move through the list and Enter toggles a row. Past 15 entries, the
|
|
46
|
+
list has a search field, and matches keep the same order. The rows do not emit
|
|
47
|
+
`highlight`: only the entries on the row do.
|
|
48
|
+
|
|
49
|
+
An entry with no `weight` keeps its given place after the ranked ones, and so
|
|
50
|
+
does "Others". The line, area and bar charts weigh a series by the sum of its
|
|
51
|
+
values' magnitudes, which is also what `maxSeries` keeps, and print no number:
|
|
52
|
+
a sum is wrong for a rate or an average. `DonutChart` weighs a slice by its
|
|
53
|
+
value and prints it, since slices are parts of a whole. `ScatterChart` passes
|
|
54
|
+
no weight, so its groups keep their order.
|
|
55
|
+
|
|
56
|
+
<ComponentPreview name="Charts-LineManySeries" csr="true" self-layout />
|
|
35
57
|
|
|
36
58
|
## Toggling
|
|
37
59
|
|
|
@@ -60,6 +60,12 @@
|
|
|
60
60
|
required: false,
|
|
61
61
|
type: 'number'
|
|
62
62
|
},
|
|
63
|
+
{
|
|
64
|
+
name: 'order',
|
|
65
|
+
description: 'The order the slices go round the ring. `\'size\'` puts the biggest first.\n`\'rows\'` keeps the rows\' order, for categories that already have one, such\nas ageing buckets or months. Either way `maxSlices` keeps the largest, and\n"Others" comes last. Defaults to `\'size\'`.',
|
|
66
|
+
required: false,
|
|
67
|
+
type: 'SliceOrder'
|
|
68
|
+
},
|
|
63
69
|
{
|
|
64
70
|
name: 'hiddenSlices',
|
|
65
71
|
description: 'Slices the legend has switched off, by name. Bind it with\n`v-model:hiddenSlices` to drive the legend from the app. Left unbound, the\nlegend owns it.',
|
|
@@ -97,6 +103,12 @@
|
|
|
97
103
|
required: false,
|
|
98
104
|
type: 'ChartPalette'
|
|
99
105
|
},
|
|
106
|
+
{
|
|
107
|
+
name: 'colors',
|
|
108
|
+
description: 'Pins a color to a slice, keyed by its category value, e.g. `{ Overdue:\n\'var(--ink-red-5)\' }`. `OTHERS_KEY` pins "Others". A category grouped into\n"Others" takes that slice\'s color. The other slices keep the palette color\nthey would have had.',
|
|
109
|
+
required: false,
|
|
110
|
+
type: 'Record<string, string>'
|
|
111
|
+
},
|
|
100
112
|
{
|
|
101
113
|
name: 'echartOptions',
|
|
102
114
|
description: 'Escape hatch: deep-merged into the echarts option the props built.',
|
|
@@ -23,6 +23,23 @@ with no "Others" slice. `select` reports the data rows behind the slice, and for
|
|
|
23
23
|
|
|
24
24
|
<ComponentPreview name="Charts-DonutOthers" csr="true" self-layout />
|
|
25
25
|
|
|
26
|
+
## Keeping the rows' order
|
|
27
|
+
|
|
28
|
+
The biggest slice comes first by default. `order="rows"` draws the slices in the order the rows arrive instead, for categories that already have an order, such as ageing buckets or months. `maxSlices` still keeps the largest slices, and "Others" comes last.
|
|
29
|
+
|
|
30
|
+
## Pinning a color
|
|
31
|
+
|
|
32
|
+
`colors` pins a color to a category, so a slice keeps its meaning whatever its size. Key it by the category value, and by `OTHERS_KEY` for "Others". A category grouped into "Others" takes that slice's color. The other slices keep the palette colors they would have had. A color can be a CSS variable, such as `var(--ink-red-5)`.
|
|
33
|
+
|
|
34
|
+
```vue
|
|
35
|
+
<DonutChart
|
|
36
|
+
:data="invoices"
|
|
37
|
+
category="status"
|
|
38
|
+
value="count"
|
|
39
|
+
:colors="{ Overdue: 'var(--ink-red-5)', Paid: 'var(--ink-green-5)' }"
|
|
40
|
+
/>
|
|
41
|
+
```
|
|
42
|
+
|
|
26
43
|
## Half ring
|
|
27
44
|
|
|
28
45
|
`variant="half"` draws the ring as a semicircle, which fits a short card.
|
|
@@ -62,7 +62,7 @@
|
|
|
62
62
|
},
|
|
63
63
|
{
|
|
64
64
|
name: 'min',
|
|
65
|
-
description: 'Bottom of the color scale. Defaults to
|
|
65
|
+
description: 'Bottom of the color scale. Defaults to 0 when no value is negative, else to\nthe smallest value in the data.',
|
|
66
66
|
required: false,
|
|
67
67
|
type: 'number'
|
|
68
68
|
},
|
|
@@ -15,6 +15,8 @@ because the data names those series, not you.
|
|
|
15
15
|
|
|
16
16
|
<ComponentPreview name="Charts-LineTrend" csr="true" self-layout />
|
|
17
17
|
|
|
18
|
+
`xAxis.format` prints the date where a value is read, such as the tooltip. It does not reach the tick labels of a time axis, which keep their levels: the year that opens a run of months, then the months.
|
|
19
|
+
|
|
18
20
|
## A numeric x axis
|
|
19
21
|
|
|
20
22
|
`xAxis.type: 'value'` treats the x column as numbers on a scale. Each point sits
|
|
@@ -73,9 +75,9 @@ and `dashed`.
|
|
|
73
75
|
|
|
74
76
|
A reference line is not a series. It has no legend entry, never shows in the
|
|
75
77
|
tooltip, and cannot be hidden, so a threshold always stays visible for
|
|
76
|
-
comparison.
|
|
77
|
-
the
|
|
78
|
-
|
|
78
|
+
comparison. The value axis stretches to reach every line, so a threshold
|
|
79
|
+
outside the data stays in view. It goes up a tick when a line at its top end
|
|
80
|
+
leaves no room for the label.
|
|
79
81
|
|
|
80
82
|
## Context in the tooltip
|
|
81
83
|
|
|
@@ -107,6 +107,12 @@
|
|
|
107
107
|
required: false,
|
|
108
108
|
type: 'NumberCardSparkline'
|
|
109
109
|
},
|
|
110
|
+
{
|
|
111
|
+
name: 'progress',
|
|
112
|
+
description: 'How far the reading has come towards a whole, drawn as a bar under it and its change.',
|
|
113
|
+
required: false,
|
|
114
|
+
type: 'NumberCardProgress'
|
|
115
|
+
},
|
|
110
116
|
{
|
|
111
117
|
name: 'card',
|
|
112
118
|
description: 'Draws the card surface: border, background, corner radius and padding. On\nby default. Set it to `false` for a chart the app has already placed inside\na card of its own, so a bordered box does not nest in a bordered box.',
|
|
@@ -27,6 +27,12 @@ of its trend line. It works like `seriesConfig[key].color` for a series. It does
|
|
|
27
27
|
not change the rest of the card, and the change keeps the color that shows
|
|
28
28
|
whether the number went up or down.
|
|
29
29
|
|
|
30
|
+
## Progress
|
|
31
|
+
|
|
32
|
+
`progress` draws a bar under the number and its change for how far the number has come towards a whole, such as disk used or revenue against a target. Pass `value` as a percent, the way `Progress` takes it. Past 100 the bar fills and a gap marks where 100 falls. The bar fills in the same blue as a sparkline, and `color` overrides it.
|
|
33
|
+
|
|
34
|
+
<ComponentPreview name="Charts-NumberProgress" csr="true" self-layout />
|
|
35
|
+
|
|
30
36
|
## The title row
|
|
31
37
|
|
|
32
38
|
`#actions` goes at the end of the row and `#title-suffix` right after the title
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Charts
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Eleven chart components in the `frappe-ui/charts` subpath, drawn with
|
|
4
4
|
[echarts](https://echarts.apache.org). Props are flat and name the columns of
|
|
5
5
|
your data (`x`, `y`, `y2`, `splitBy`, `category`, `value`), so you can save a
|
|
6
6
|
chart as one typed object and render it with `v-bind="savedChart"`.
|
|
@@ -12,12 +12,15 @@ import { BarChart, LineChart } from 'frappe-ui/charts'
|
|
|
12
12
|
Importing the subpath also loads the `--chart-*` color tokens. See
|
|
13
13
|
[Chart colors](/docs/charts/colors) for the three ramps and how to change
|
|
14
14
|
them. The `palette` prop picks a ramp by name (`categorical`, `sequential` or
|
|
15
|
-
`diverging`) or takes a list of colors.
|
|
15
|
+
`diverging`) or takes a list of colors. Any color a chart takes can be a CSS
|
|
16
|
+
variable such as `var(--brand)`. It resolves against the chart's own element,
|
|
17
|
+
and again when the theme changes.
|
|
16
18
|
|
|
17
19
|
Each echarts chart registers only the echarts modules it needs, so importing
|
|
18
20
|
`DonutChart` loads only the pie module. The three axis charts share the bar and
|
|
19
21
|
line modules, because each of them can draw bars and lines. `FunnelChart` and
|
|
20
|
-
`NumberCard` do not use echarts. Both draw their own SVG.
|
|
22
|
+
`NumberCard` do not use echarts. Both draw their own SVG. `PercentageBarChart`
|
|
23
|
+
does not use echarts either. It draws divs.
|
|
21
24
|
|
|
22
25
|
## Data shapes
|
|
23
26
|
|
|
@@ -41,8 +44,10 @@ Use it for a combo chart, or to fill one line of a `LineChart`.
|
|
|
41
44
|
| [LineChart](/docs/charts/linechart) | Trends, a second value axis, gaps |
|
|
42
45
|
| [AreaChart](/docs/charts/areachart) | Lines with a fill |
|
|
43
46
|
| [DonutChart](/docs/charts/donutchart) | Share of a total |
|
|
47
|
+
| [PercentageBarChart](/docs/charts/percentagebarchart) | Share of a total, as one bar |
|
|
44
48
|
| [FunnelChart](/docs/charts/funnelchart) | Drop-off from stage to stage |
|
|
45
49
|
| [HeatmapChart](/docs/charts/heatmapchart) | Size of a value across two dimensions |
|
|
50
|
+
| [CalendarHeatmapChart](/docs/charts/calendarheatmapchart) | A value for each day |
|
|
46
51
|
| [ScatterChart](/docs/charts/scatterchart) | Two measures against each other |
|
|
47
52
|
| [SankeyChart](/docs/charts/sankeychart) | Flow from a source to a target |
|
|
48
53
|
| [NumberCard](/docs/charts/numbercard) | One number and its change |
|
|
@@ -172,7 +177,8 @@ is instant.
|
|
|
172
177
|
## The echarts instance
|
|
173
178
|
|
|
174
179
|
Every echarts-backed chart hands back its instance as `chart` on a template ref.
|
|
175
|
-
`FunnelChart` and `
|
|
180
|
+
`FunnelChart`, `NumberCard` and `PercentageBarChart` draw no echarts plot and
|
|
181
|
+
hand back nothing.
|
|
176
182
|
|
|
177
183
|
```vue
|
|
178
184
|
<script setup lang="ts">
|
|
@@ -264,7 +270,8 @@ Three series get three evenly spaced colors, not the first three.
|
|
|
264
270
|
### `OTHERS_KEY`
|
|
265
271
|
|
|
266
272
|
The key of the series that collects the extra series when you set a limit:
|
|
267
|
-
`maxSeries` on an axis chart, `maxSlices` on a donut
|
|
268
|
-
group that is really named "Others" does not clash with
|
|
273
|
+
`maxSeries` on an axis chart, `maxSlices` on a donut or a percentage bar. It is
|
|
274
|
+
a reserved key, so a group that is really named "Others" does not clash with
|
|
275
|
+
it. Use
|
|
269
276
|
`seriesConfig[OTHERS_KEY]` to rename or recolor it like any other series. Its
|
|
270
277
|
label is "Others" unless you set a `label`.
|