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.
Files changed (96) hide show
  1. package/experimental/Calendar/calendarUtils.ts +33 -21
  2. package/experimental/MultiEmailInput/MultiEmailInput.vue +64 -12
  3. package/experimental/MultiEmailInput/types.ts +12 -3
  4. package/experimental/Stepper/StepIndicator.vue +129 -0
  5. package/experimental/Stepper/Stepper.api.md +117 -0
  6. package/experimental/Stepper/Stepper.md +95 -0
  7. package/experimental/Stepper/Stepper.vue +82 -0
  8. package/experimental/Stepper/StepperHorizontal.vue +93 -0
  9. package/experimental/Stepper/StepperVertical.vue +291 -0
  10. package/experimental/Stepper/index.ts +11 -0
  11. package/experimental/Stepper/resolve.ts +87 -0
  12. package/experimental/Stepper/types.ts +89 -0
  13. package/experimental.ts +2 -0
  14. package/package.json +1 -1
  15. package/src/charts/CalendarHeatmapChart.vue +353 -0
  16. package/src/charts/DonutChart.vue +34 -58
  17. package/src/charts/HeatmapChart.vue +26 -64
  18. package/src/charts/NumberCard.vue +62 -7
  19. package/src/charts/PercentageBarChart.vue +243 -0
  20. package/src/charts/SankeyChart.vue +14 -11
  21. package/src/charts/ScatterChart.vue +24 -20
  22. package/src/charts/axisChartCommon.ts +182 -18
  23. package/src/charts/axisFormat.ts +8 -3
  24. package/src/charts/calendarHeatmapOptions.ts +604 -0
  25. package/src/charts/colorMath.ts +26 -0
  26. package/src/charts/components/ChartContainer.vue +63 -53
  27. package/src/charts/components/ChartLegend.vue +216 -24
  28. package/src/charts/components/ChartScale.vue +85 -0
  29. package/src/charts/core/dataLabelFit.ts +45 -6
  30. package/src/charts/core/useAxisChart.ts +36 -19
  31. package/src/charts/core/useChart.ts +6 -1
  32. package/src/charts/core/usePlotKeyboard.ts +13 -2
  33. package/src/charts/docs/BarChart.md +11 -3
  34. package/src/charts/docs/CalendarHeatmapChart.api.md +165 -0
  35. package/src/charts/docs/CalendarHeatmapChart.md +33 -0
  36. package/src/charts/docs/ChartContainer.api.md +6 -0
  37. package/src/charts/docs/ChartLegend.api.md +1 -1
  38. package/src/charts/docs/ChartLegend.md +25 -3
  39. package/src/charts/docs/DonutChart.api.md +12 -0
  40. package/src/charts/docs/DonutChart.md +17 -0
  41. package/src/charts/docs/HeatmapChart.api.md +1 -1
  42. package/src/charts/docs/LineChart.md +5 -3
  43. package/src/charts/docs/NumberCard.api.md +6 -0
  44. package/src/charts/docs/NumberCard.md +6 -0
  45. package/src/charts/docs/Overview.md +13 -6
  46. package/src/charts/docs/PercentageBarChart.api.md +148 -0
  47. package/src/charts/docs/PercentageBarChart.md +42 -0
  48. package/src/charts/docs/ScatterChart.md +2 -3
  49. package/src/charts/donutChartOptions.ts +22 -130
  50. package/src/charts/format.ts +4 -1
  51. package/src/charts/heatmapOptions.ts +17 -12
  52. package/src/charts/hiddenSeries.ts +8 -3
  53. package/src/charts/index.ts +12 -0
  54. package/src/charts/legendOverflow.ts +40 -0
  55. package/src/charts/numberCardFormat.ts +19 -13
  56. package/src/charts/referenceLines.ts +2 -1
  57. package/src/charts/scatterOptions.ts +16 -3
  58. package/src/charts/seriesData.ts +8 -3
  59. package/src/charts/slices.ts +228 -0
  60. package/src/charts/tokens.ts +99 -0
  61. package/src/charts/types.ts +318 -9
  62. package/src/components/Avatar/Avatar.md +27 -2
  63. package/src/components/Avatar/Avatar.vue +29 -12
  64. package/src/components/Combobox/Combobox.vue +9 -2
  65. package/src/components/Combobox/ComboboxResults.vue +6 -1
  66. package/src/components/Combobox/utils.ts +2 -1
  67. package/src/components/Dialog/Dialog.md +3 -1
  68. package/src/components/Duration/Duration.api.md +16 -3
  69. package/src/components/Duration/Duration.md +21 -0
  70. package/src/components/Duration/Duration.vue +29 -8
  71. package/src/components/Duration/duration.ts +105 -44
  72. package/src/components/Duration/index.ts +1 -0
  73. package/src/components/Duration/types.ts +30 -1
  74. package/src/components/Menu/utils.ts +3 -2
  75. package/src/components/MultiSelect/MultiSelect.api.md +5 -0
  76. package/src/components/MultiSelect/MultiSelect.vue +34 -0
  77. package/src/components/MultiSelect/MultiSelectResults.vue +3 -4
  78. package/src/components/MultiSelect/types.ts +6 -0
  79. package/src/components/Select/Select.vue +4 -4
  80. package/src/components/Select/utils.ts +1 -0
  81. package/src/components/Switch/Switch.vue +3 -3
  82. package/src/components/shared/selection/utils.ts +8 -1
  83. package/src/data-fetching/useCall/useCall.ts +25 -26
  84. package/src/data-fetching/useFrappeFetch.ts +48 -2
  85. package/src/data-fetching/useList/useList.ts +11 -3
  86. package/src/data-fetching/utils.ts +15 -1
  87. package/src/molecules/editor/components/MediaNodeView.vue +10 -1
  88. package/src/molecules/editor/components/MediaResizeGuide.vue +71 -0
  89. package/src/molecules/editor/components/media-node-view-utils.ts +7 -0
  90. package/src/molecules/editor/composables/useNodeViewResize.ts +142 -10
  91. package/src/molecules/editor/extensions/iframe/IframeNodeView.vue +3 -1
  92. package/src/molecules/editor/useEditor.ts +12 -6
  93. package/src/utils/dialog.ts +37 -14
  94. package/tailwind/content.js +1 -0
  95. package/vite/README.md +5 -3
  96. 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 { dataLabelOverflow, nextAxisMax } from './dataLabelFit'
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, formatLabel, formatValue } from '../format'
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 = computed(args.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
- ? formatLabel(config.value.y2Axis.title)
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 past the plot. The value axis
178
- * goes up one tick to make room for it, so the plot keeps its place in the
179
- * card whatever the numbers are. An axis end the caller fixed is theirs.
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 = dataLabelOverflow(instance, side, option.grid[side])
196
- if (overflow === null || overflow <= 0) return
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 max = nextAxisMax(instance, valueAxis)
199
- if (max === null) return
203
+ const tick = nextAxisTick(instance, valueAxis)
204
+ if (tick === null) return
200
205
  raisedFor = option
201
- instance.setOption({ [valueAxis]: [{ max }] })
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
- config.value.series.length,
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
- step(1)
180
+ along(1)
170
181
  break
171
182
  case 'ArrowLeft':
172
- step(-1)
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. A line outside the plotted
114
- range is not drawn, because the scale follows the data, not the lines. Set
115
- `yAxis.min` or `max` to bring a distant target into view.
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
- The row wraps and never scrolls. It takes as many lines as it needs and the plot
33
- gets shorter, which the chart's resize observer picks up. A scrolling legend
34
- would hide series names that most users never scroll to.
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 the smallest value in the data.',
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. A line outside the plotted range is not drawn, because stretching
77
- the scale to fit a distant target would flatten the data. Set `yAxis.min` or
78
- `max` instead.
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
- Nine chart components in the `frappe-ui/charts` subpath, drawn with
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 `NumberCard` draw no echarts plot and hand back nothing.
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. It is a reserved key, so a
268
- group that is really named "Others" does not clash with it. Use
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`.