frappe-ui 1.0.2 → 1.2.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 (194) hide show
  1. package/experimental/Calendar/CalendarEventRow.vue +0 -4
  2. package/experimental/Calendar/calendarUtils.ts +33 -21
  3. package/experimental/CommandPalette/CommandPaletteItem.vue +9 -1
  4. package/experimental/MultiEmailInput/MultiEmailInput.vue +64 -12
  5. package/experimental/MultiEmailInput/types.ts +12 -3
  6. package/experimental/SpriteIcons/IconPicker.vue +2 -1
  7. package/experimental/Stepper/StepIndicator.vue +129 -0
  8. package/experimental/Stepper/Stepper.api.md +117 -0
  9. package/experimental/Stepper/Stepper.md +95 -0
  10. package/experimental/Stepper/Stepper.vue +82 -0
  11. package/experimental/Stepper/StepperHorizontal.vue +93 -0
  12. package/experimental/Stepper/StepperVertical.vue +291 -0
  13. package/experimental/Stepper/index.ts +11 -0
  14. package/experimental/Stepper/resolve.ts +87 -0
  15. package/experimental/Stepper/types.ts +89 -0
  16. package/experimental.ts +2 -21
  17. package/package.json +1 -3
  18. package/src/charts/CalendarHeatmapChart.vue +353 -0
  19. package/src/charts/DonutChart.vue +34 -58
  20. package/src/charts/HeatmapChart.vue +26 -64
  21. package/src/charts/NumberCard.vue +62 -7
  22. package/src/charts/PercentageBarChart.vue +243 -0
  23. package/src/charts/SankeyChart.vue +14 -11
  24. package/src/charts/ScatterChart.vue +24 -20
  25. package/src/charts/axisChartCommon.ts +182 -18
  26. package/src/charts/axisFormat.ts +8 -3
  27. package/src/charts/calendarHeatmapOptions.ts +604 -0
  28. package/src/charts/colorMath.ts +26 -0
  29. package/src/charts/components/ChartContainer.vue +63 -53
  30. package/src/charts/components/ChartLegend.vue +216 -24
  31. package/src/charts/components/ChartScale.vue +85 -0
  32. package/src/charts/core/dataLabelFit.ts +45 -6
  33. package/src/charts/core/useAxisChart.ts +36 -19
  34. package/src/charts/core/useChart.ts +6 -1
  35. package/src/charts/core/usePlotKeyboard.ts +13 -2
  36. package/src/charts/docs/BarChart.md +11 -3
  37. package/src/charts/docs/CalendarHeatmapChart.api.md +165 -0
  38. package/src/charts/docs/CalendarHeatmapChart.md +33 -0
  39. package/src/charts/docs/ChartContainer.api.md +6 -0
  40. package/src/charts/docs/ChartLegend.api.md +1 -1
  41. package/src/charts/docs/ChartLegend.md +25 -3
  42. package/src/charts/docs/DonutChart.api.md +12 -0
  43. package/src/charts/docs/DonutChart.md +17 -0
  44. package/src/charts/docs/HeatmapChart.api.md +1 -1
  45. package/src/charts/docs/LineChart.md +5 -3
  46. package/src/charts/docs/NumberCard.api.md +6 -0
  47. package/src/charts/docs/NumberCard.md +6 -0
  48. package/src/charts/docs/Overview.md +13 -6
  49. package/src/charts/docs/PercentageBarChart.api.md +148 -0
  50. package/src/charts/docs/PercentageBarChart.md +42 -0
  51. package/src/charts/docs/ScatterChart.md +2 -3
  52. package/src/charts/donutChartOptions.ts +22 -130
  53. package/src/charts/format.ts +4 -1
  54. package/src/charts/heatmapOptions.ts +17 -12
  55. package/src/charts/hiddenSeries.ts +8 -3
  56. package/src/charts/index.ts +12 -0
  57. package/src/charts/legendOverflow.ts +40 -0
  58. package/src/charts/numberCardFormat.ts +19 -13
  59. package/src/charts/referenceLines.ts +2 -1
  60. package/src/charts/scatterOptions.ts +16 -3
  61. package/src/charts/seriesData.ts +8 -3
  62. package/src/charts/slices.ts +228 -0
  63. package/src/charts/tokens.ts +99 -0
  64. package/src/charts/types.ts +318 -9
  65. package/src/components/Avatar/Avatar.md +27 -2
  66. package/src/components/Avatar/Avatar.vue +29 -12
  67. package/src/components/Breadcrumbs/Breadcrumbs.vue +2 -1
  68. package/src/components/Combobox/Combobox.vue +9 -2
  69. package/src/components/Combobox/ComboboxResults.vue +6 -1
  70. package/src/components/Combobox/utils.ts +2 -1
  71. package/src/components/DatePicker/DatePicker.md +7 -0
  72. package/src/components/DatePicker/DatePicker.vue +6 -0
  73. package/src/components/DatePicker/DateTimePicker.vue +6 -0
  74. package/src/components/DatePicker/composables.ts +18 -1
  75. package/src/components/DatePicker/utils.ts +53 -0
  76. package/src/components/Dialog/Dialog.md +3 -1
  77. package/src/components/Duration/Duration.api.md +16 -3
  78. package/src/components/Duration/Duration.md +21 -0
  79. package/src/components/Duration/Duration.vue +29 -8
  80. package/src/components/Duration/duration.ts +105 -44
  81. package/src/components/Duration/index.ts +1 -0
  82. package/src/components/Duration/types.ts +30 -1
  83. package/src/components/HoverCard/HoverCard.vue +21 -5
  84. package/src/components/Menu/utils.ts +3 -2
  85. package/src/components/MobileNav/MobileNavItem.vue +3 -22
  86. package/src/components/MultiSelect/MultiSelect.api.md +5 -0
  87. package/src/components/MultiSelect/MultiSelect.vue +34 -0
  88. package/src/components/MultiSelect/MultiSelectResults.vue +3 -4
  89. package/src/components/MultiSelect/types.ts +6 -0
  90. package/src/components/Select/Select.vue +4 -4
  91. package/src/components/Select/utils.ts +1 -0
  92. package/src/components/SettingsDialog/SettingsDialog.api.md +7 -2
  93. package/src/components/SettingsDialog/SettingsDialog.md +2 -1
  94. package/src/components/SettingsDialog/SettingsRow.vue +12 -2
  95. package/src/components/Sidebar/SidebarItem.vue +3 -33
  96. package/src/components/SidebarRail/SidebarRailItem.vue +4 -17
  97. package/src/components/Switch/Switch.vue +3 -3
  98. package/src/components/Tooltip/Tooltip.vue +8 -0
  99. package/src/components/shared/deferredTrigger.ts +174 -0
  100. package/src/components/shared/navLink.ts +45 -0
  101. package/src/components/shared/selection/utils.ts +8 -1
  102. package/src/data-fetching/useCall/useCall.ts +25 -26
  103. package/src/data-fetching/useFrappeFetch.ts +48 -2
  104. package/src/data-fetching/useList/useList.ts +11 -3
  105. package/src/data-fetching/utils.ts +15 -1
  106. package/src/molecules/editor/components/MediaNodeView.vue +10 -1
  107. package/src/molecules/editor/components/MediaResizeGuide.vue +71 -0
  108. package/src/molecules/editor/components/media-node-view-utils.ts +7 -0
  109. package/src/molecules/editor/composables/useNodeViewResize.ts +142 -10
  110. package/src/molecules/editor/extensions/attachment/attachment-engine.ts +1 -1
  111. package/src/molecules/editor/extensions/content-paste/paste-html-utils.ts +16 -6
  112. package/src/molecules/editor/extensions/iframe/IframeNodeView.vue +29 -10
  113. package/src/molecules/editor/extensions/iframe/iframe-allowlist.ts +35 -16
  114. package/src/molecules/editor/extensions/iframe/iframe-embed-utils.ts +1 -1
  115. package/src/molecules/editor/extensions/iframe/iframe-extension.ts +30 -30
  116. package/src/molecules/editor/extensions/link/LinkEditorPopup.vue +1 -1
  117. package/src/molecules/editor/extensions/link/link-paste-plugin.ts +1 -1
  118. package/src/molecules/editor/extensions/shared/media-upload-engine.ts +1 -1
  119. package/src/molecules/editor/useEditor.ts +12 -6
  120. package/src/molecules/list/ListRow.vue +8 -1
  121. package/src/utils/dialog.ts +57 -16
  122. package/src/{molecules/editor/extensions/shared → utils}/url-safety.ts +28 -16
  123. package/tailwind/content.js +1 -1
  124. package/tailwind/plugin.js +22 -0
  125. package/vite/README.md +5 -3
  126. package/vite/codeLanguages.js +41 -17
  127. package/vite/doctypeInterfaceGenerator.js +52 -39
  128. package/vitepress/index.node.ts +0 -2
  129. package/experimental/TextEditor/TextEditor.api.md +0 -161
  130. package/experimental/TextEditor/TextEditor.vue +0 -298
  131. package/experimental/TextEditor/classIcon.ts +0 -21
  132. package/experimental/TextEditor/commands.js +0 -344
  133. package/experimental/TextEditor/components/CodeBlockComponent.vue +0 -103
  134. package/experimental/TextEditor/components/FontColor.vue +0 -153
  135. package/experimental/TextEditor/components/ImageViewerModal.vue +0 -463
  136. package/experimental/TextEditor/components/InsertImage.vue +0 -54
  137. package/experimental/TextEditor/components/InsertLink.vue +0 -13
  138. package/experimental/TextEditor/components/InsertVideo.vue +0 -14
  139. package/experimental/TextEditor/components/LinkPopup.vue +0 -99
  140. package/experimental/TextEditor/components/MediaNodeView.vue +0 -398
  141. package/experimental/TextEditor/components/MentionList.vue +0 -95
  142. package/experimental/TextEditor/components/TextEditorBubbleMenu.vue +0 -78
  143. package/experimental/TextEditor/components/TextEditorFixedMenu.vue +0 -78
  144. package/experimental/TextEditor/components/TextEditorFloatingMenu.vue +0 -61
  145. package/experimental/TextEditor/components/TextEditorMenu.vue +0 -218
  146. package/experimental/TextEditor/components/index.js +0 -0
  147. package/experimental/TextEditor/extensions/code-block.ts +0 -119
  148. package/experimental/TextEditor/extensions/color/color-extension.ts +0 -140
  149. package/experimental/TextEditor/extensions/color/color-styles.css +0 -25
  150. package/experimental/TextEditor/extensions/color/index.ts +0 -2
  151. package/experimental/TextEditor/extensions/content-paste-extension.ts +0 -160
  152. package/experimental/TextEditor/extensions/copy-styles.ts +0 -160
  153. package/experimental/TextEditor/extensions/emoji/EmojiList.vue +0 -55
  154. package/experimental/TextEditor/extensions/emoji/emoji-extension.ts +0 -55
  155. package/experimental/TextEditor/extensions/emoji/emojis.json +0 -7422
  156. package/experimental/TextEditor/extensions/heading/heading.ts +0 -20
  157. package/experimental/TextEditor/extensions/highlight/highlight-extension.ts +0 -241
  158. package/experimental/TextEditor/extensions/highlight/highlight-styles.css +0 -31
  159. package/experimental/TextEditor/extensions/highlight/index.ts +0 -2
  160. package/experimental/TextEditor/extensions/iframe/IframeNodeView.vue +0 -308
  161. package/experimental/TextEditor/extensions/iframe/InsertIframe.vue +0 -209
  162. package/experimental/TextEditor/extensions/iframe/iframe-extension.ts +0 -404
  163. package/experimental/TextEditor/extensions/iframe/index.ts +0 -11
  164. package/experimental/TextEditor/extensions/iframe/utils.ts +0 -283
  165. package/experimental/TextEditor/extensions/image/image-extension.ts +0 -661
  166. package/experimental/TextEditor/extensions/image/index.ts +0 -5
  167. package/experimental/TextEditor/extensions/image-group/ImageGroupNodeView.vue +0 -182
  168. package/experimental/TextEditor/extensions/image-group/ImageGroupUploadDialog.vue +0 -740
  169. package/experimental/TextEditor/extensions/image-group/image-group-extension.ts +0 -187
  170. package/experimental/TextEditor/extensions/image-viewer-extension.ts +0 -162
  171. package/experimental/TextEditor/extensions/link/index.ts +0 -1
  172. package/experimental/TextEditor/extensions/link/link-extension.ts +0 -323
  173. package/experimental/TextEditor/extensions/link/linkPasteHandler.ts +0 -51
  174. package/experimental/TextEditor/extensions/mention/index.ts +0 -1
  175. package/experimental/TextEditor/extensions/mention/mention-extension.ts +0 -204
  176. package/experimental/TextEditor/extensions/mention/style.css +0 -11
  177. package/experimental/TextEditor/extensions/shared/color-utils.ts +0 -236
  178. package/experimental/TextEditor/extensions/slash-commands/SlashCommandsList.vue +0 -59
  179. package/experimental/TextEditor/extensions/slash-commands/slash-commands-extension.ts +0 -184
  180. package/experimental/TextEditor/extensions/suggestion/SuggestionList.vue +0 -130
  181. package/experimental/TextEditor/extensions/suggestion/createSuggestionExtension.ts +0 -151
  182. package/experimental/TextEditor/extensions/suggestion/index.ts +0 -5
  183. package/experimental/TextEditor/extensions/tag/index.ts +0 -1
  184. package/experimental/TextEditor/extensions/tag/tag-extension.ts +0 -170
  185. package/experimental/TextEditor/extensions/toc-node/TocNodeView.vue +0 -439
  186. package/experimental/TextEditor/extensions/toc-node/index.ts +0 -3
  187. package/experimental/TextEditor/extensions/toc-node/toc-node-extension.ts +0 -167
  188. package/experimental/TextEditor/extensions/video-extension.ts +0 -653
  189. package/experimental/TextEditor/hljs-github.css +0 -197
  190. package/experimental/TextEditor/index.ts +0 -21
  191. package/experimental/TextEditor/style.css +0 -190
  192. package/experimental/TextEditor/types.ts +0 -72
  193. package/experimental/TextEditor/utils.js +0 -11
  194. package/src/utils/url-validation.ts +0 -39
@@ -62,6 +62,8 @@ export type ChartYAxisConfig = {
62
62
  title?: string
63
63
  min?: number
64
64
  max?: number
65
+ /** Ticks on whole numbers only. Unset decides from the values on the axis. */
66
+ integer?: boolean
65
67
  echartOptions?: EchartOptionsOverride
66
68
  }
67
69
 
@@ -131,8 +133,7 @@ export type ReferenceLineLabelPlacement =
131
133
  export type ReferenceLine = {
132
134
  /**
133
135
  * Where the line sits: a number on a value axis, or whatever the category
134
- * column holds on the category axis. A value outside the range the plot
135
- * covers is not drawn; the scale follows the data, not the annotation.
136
+ * column holds on the category axis. A value axis stretches to reach it.
136
137
  */
137
138
  value: number | string | Date
138
139
  /**
@@ -226,12 +227,19 @@ export type DonutChartConfig = {
226
227
  * readable long before the palette runs out, so it defaults to 9.
227
228
  */
228
229
  maxSlices?: number
230
+ /** Slices go biggest first, or as the rows arrive. Defaults to `'size'`. */
231
+ order?: SliceOrder
229
232
  /**
230
233
  * Ramp slice colors are drawn from. Defaults to `'categorical'`: slices are
231
234
  * unrelated categories, not steps of one magnitude, so they read as separate
232
235
  * hues rather than as a ramp.
233
236
  */
234
237
  palette?: ChartPalette
238
+ /**
239
+ * Pins a color to a slice, keyed by its category value, or by `OTHERS_KEY`
240
+ * for "Others". The rest take the palette, as if none were pinned.
241
+ */
242
+ colors?: Record<string, string>
235
243
  /**
236
244
  * Prints each slice's name and share next to the ring. Off by default: the
237
245
  * legend carries the same information without the leader lines.
@@ -248,14 +256,20 @@ export type DonutChartConfig = {
248
256
 
249
257
  export type DonutVariant = 'full' | 'half'
250
258
 
251
- /** One arc of the ring, after sorting, "Others" grouping and color assignment. */
259
+ export type SliceOrder = 'size' | 'rows'
260
+
261
+ /** One arc of the ring, after ordering, "Others" grouping and color assignment. */
252
262
  export type DonutSlice = {
253
263
  /** Identity used by echarts actions and the legend. Unique within the ring. */
254
264
  name: string
255
265
  /** The category value as it should read; not unique. */
256
266
  label: string
257
267
  value: number
258
- /** Share of the *visible* total, so hiding a slice re-percentages the rest. */
268
+ /**
269
+ * Share of the *visible* total, so hiding a slice re-percentages the rest.
270
+ * Rounded with the other slices' to whole points that add up to 100; a share
271
+ * under 1 stays as it is.
272
+ */
259
273
  percent: number
260
274
  color: string
261
275
  hidden: boolean
@@ -270,7 +284,11 @@ export type DonutSliceEvent = {
270
284
  /** The slice as it reads, i.e. the category value or "Others". */
271
285
  label: string
272
286
  value: number
273
- /** Share of the *visible* total, so a hidden slice changes what this reads. */
287
+ /**
288
+ * Share of the *visible* total, so a hidden slice changes what this reads.
289
+ * The share the legend printed: whole points that add up to 100 across the
290
+ * slices, except a share under 1, which stays as it is.
291
+ */
274
292
  percent: number
275
293
  /** One row, or every grouped row when the "Others" slice was clicked. */
276
294
  rows: Record<string, any>[]
@@ -354,7 +372,10 @@ export type HeatmapChartConfig = {
354
372
  * on zero unless `min`/`max` say otherwise.
355
373
  */
356
374
  palette?: HeatmapPalette
357
- /** Bottom of the color scale. Defaults to the smallest value in the data. */
375
+ /**
376
+ * Bottom of the color scale. Defaults to 0 when no value is negative, else to
377
+ * the smallest value in the data.
378
+ */
358
379
  min?: number
359
380
  /** Top of the color scale. Defaults to the largest value in the data. */
360
381
  max?: number
@@ -407,6 +428,117 @@ export type HeatmapCellEvent = {
407
428
  row: Record<string, any>
408
429
  }
409
430
 
431
+ /** The weekday each column of a calendar heatmap starts on. */
432
+ export type CalendarHeatmapWeekStart =
433
+ | 'sunday'
434
+ | 'monday'
435
+ | 'tuesday'
436
+ | 'wednesday'
437
+ | 'thursday'
438
+ | 'friday'
439
+ | 'saturday'
440
+
441
+ export type CalendarHeatmapChartConfig = {
442
+ /** One row per day. Of two on the same day, the later one is drawn. */
443
+ data: Record<string, any>[]
444
+ /**
445
+ * Row key holding the day: a `Date`, or an ISO string such as `2024-03-01`.
446
+ * A time or offset after the date is ignored.
447
+ */
448
+ dateColumn: string
449
+ /** Row key holding the magnitude the day is colored by. */
450
+ valueColumn: string
451
+ title?: string
452
+ subtitle?: string
453
+ /** As on `HeatmapChartConfig`. */
454
+ palette?: HeatmapPalette
455
+ /**
456
+ * Bottom of the color scale. Defaults to 0 when no day is negative, else to
457
+ * the smallest day in the range.
458
+ */
459
+ min?: number
460
+ /**
461
+ * Top of the color scale. Defaults to the largest day in the range. Days
462
+ * above it draw in the deepest color, and the scale reads `≥ max`.
463
+ */
464
+ max?: number
465
+ /**
466
+ * First day drawn. Defaults to the first of the month the data starts in.
467
+ * Given with `end`, the range is drawn even with no data in it.
468
+ */
469
+ start?: string | Date
470
+ /** Last day drawn. Defaults to the last of the month the data ends in. */
471
+ end?: string | Date
472
+ /** Defaults to the dayjs locale's week start, else `'sunday'`. */
473
+ weekStart?: CalendarHeatmapWeekStart
474
+ echartOptions?: EchartOptionsOverride
475
+ }
476
+
477
+ /** One day that has data, after color assignment. */
478
+ export type CalendarHeatmapCell = {
479
+ /** The day, as `YYYY-MM-DD`. */
480
+ date: string
481
+ value: number
482
+ color: string
483
+ /** The row drawn for the day. */
484
+ row: Record<string, any>
485
+ }
486
+
487
+ /** One day drawn, with data or without, and the mark echarts draws it as. */
488
+ export type CalendarHeatmapDay = {
489
+ /** The day, as `YYYY-MM-DD`. */
490
+ date: string
491
+ /** The band the day is drawn in. */
492
+ band: number
493
+ /** The day's data, or none for a day with no row. */
494
+ cell?: CalendarHeatmapCell
495
+ /** The series that draws the day: its band's data series, or its empty one. */
496
+ seriesIndex: number
497
+ /** The day's place in that series. */
498
+ dataIndex: number
499
+ }
500
+
501
+ /** One row of weeks. A range longer than a year draws one per twelve months. */
502
+ export type CalendarHeatmapBand = {
503
+ /** First day drawn in the band, as `YYYY-MM-DD`. */
504
+ start: string
505
+ /** Last day drawn in the band, as `YYYY-MM-DD`. */
506
+ end: string
507
+ /**
508
+ * First and last day the band lays out. Past a year, a whole twelve months
509
+ * from the range's first month, so months line up from band to band.
510
+ */
511
+ span: [string, string]
512
+ /** Week columns the band spans. */
513
+ weeks: number
514
+ /** The band's days that have data, in date order. */
515
+ cells: CalendarHeatmapCell[]
516
+ }
517
+
518
+ /** The calendar as the plot, the tooltip and the ramp scale all read it. */
519
+ export type CalendarHeatmapGrid = {
520
+ /** None when there is nothing to draw. */
521
+ bands: CalendarHeatmapBand[]
522
+ /** Every day that has data, in date order. */
523
+ cells: CalendarHeatmapCell[]
524
+ /** Every day drawn, in date order. */
525
+ days: CalendarHeatmapDay[]
526
+ /** Bottom of the color scale, config or data. */
527
+ min: number
528
+ /** Top of the color scale, config or data. */
529
+ max: number
530
+ /** The ramp the scale runs along, low end first. */
531
+ stops: string[]
532
+ }
533
+
534
+ export type CalendarHeatmapCellEvent = {
535
+ /** The day, as `YYYY-MM-DD`. */
536
+ date: string
537
+ value: number
538
+ /** The row drawn for the day. */
539
+ row: Record<string, any>
540
+ }
541
+
410
542
  export type NumberCardConfig = {
411
543
  title: string
412
544
  /** Null renders the empty state; a KPI with no number is not a zero. */
@@ -433,6 +565,19 @@ export type NumberCardConfig = {
433
565
  dir?: ChartDir
434
566
  /** A trend across the bottom of the card: shape only, no axes to read against. */
435
567
  sparkline?: NumberCardSparkline
568
+ /** How far the reading has come towards a whole, drawn as a bar under it and its change. */
569
+ progress?: NumberCardProgress
570
+ }
571
+
572
+ export type NumberCardProgress = {
573
+ /**
574
+ * Percent of the whole, as `Progress` takes it. The caller works it out: a
575
+ * reading against its target, or a percent reading as it stands. Past 100 the
576
+ * bar fills and a gap marks where 100 falls.
577
+ */
578
+ value: number
579
+ /** Overrides the sequential-palette blue the bar fills in. */
580
+ color?: string
436
581
  }
437
582
 
438
583
  export type NumberCardSparkline = {
@@ -594,6 +739,17 @@ export type ChartLegendItem = {
594
739
  hidden: boolean
595
740
  /** Muted note after the label, e.g. a donut slice's share of the total. */
596
741
  hint?: string
742
+ /**
743
+ * What the series is worth across the chart, e.g. the sum of its values'
744
+ * magnitudes, which is what `maxSeries` caps by. Ranks the entries when
745
+ * they do not fit on one row; left out, the entry keeps its given place.
746
+ */
747
+ weight?: number
748
+ /**
749
+ * The series' value as the chart formats it, printed in the "+N more" list,
750
+ * e.g. a donut slice's measure. Left out, the row prints no number.
751
+ */
752
+ formattedValue?: string
597
753
  }
598
754
 
599
755
  export type ChartTooltipItem = {
@@ -686,7 +842,12 @@ export type ChartXAxisOptions = {
686
842
  type?: 'category' | 'time' | 'value'
687
843
  /** Label granularity on a time axis. Inferred from the spacing of the data. */
688
844
  timeGrain?: TimeGrain
689
- /** Prints each category label. Takes whatever the column holds. */
845
+ /**
846
+ * Prints each category label. Takes whatever the column holds.
847
+ *
848
+ * On a time axis it prints the date where a value is read, such as the
849
+ * tooltip, and leaves the tick labels alone: they keep their levels.
850
+ */
690
851
  format?: ChartCategoryFormatter
691
852
  /** Escape hatch: deep-merged into this axis' echarts option. */
692
853
  echartOptions?: EchartOptionsOverride
@@ -704,6 +865,12 @@ export type ChartValueAxisOptions = {
704
865
  max?: number
705
866
  /** Prints each tick label, and every value this axis carries elsewhere. */
706
867
  format?: ChartValueFormatter
868
+ /**
869
+ * Puts the ticks on whole numbers only, for a count that has no half. Left
870
+ * out, it is on when every value the axis plots is a whole number, which
871
+ * only changes a scale small enough for echarts to split a unit.
872
+ */
873
+ integer?: boolean
707
874
  /**
708
875
  * Escape hatch: deep-merged into this axis' echarts option. On a
709
876
  * `stacked: 'normalized'` chart the percent formatter wins over an
@@ -905,6 +1072,13 @@ export type DonutChartProps = ChartBaseProps & {
905
1072
  * the palette runs out.
906
1073
  */
907
1074
  maxSlices?: number
1075
+ /**
1076
+ * The order the slices go round the ring. `'size'` puts the biggest first.
1077
+ * `'rows'` keeps the rows' order, for categories that already have one, such
1078
+ * as ageing buckets or months. Either way `maxSlices` keeps the largest, and
1079
+ * "Others" comes last. Defaults to `'size'`.
1080
+ */
1081
+ order?: SliceOrder
908
1082
  /**
909
1083
  * Slices the legend has switched off, by name. Bind it with
910
1084
  * `v-model:hiddenSlices` to drive the legend from the app. Left unbound, the
@@ -925,10 +1099,57 @@ export type DonutChartProps = ChartBaseProps & {
925
1099
  format?: ChartValueFormatter
926
1100
  /** Defaults to `'categorical'`: slices are unrelated categories, not steps. */
927
1101
  palette?: ChartPalette
1102
+ /**
1103
+ * Pins a color to a slice, keyed by its category value, e.g. `{ Overdue:
1104
+ * 'var(--ink-red-5)' }`. `OTHERS_KEY` pins "Others". A category grouped into
1105
+ * "Others" takes that slice's color. The other slices keep the palette color
1106
+ * they would have had.
1107
+ */
1108
+ colors?: Record<string, string>
928
1109
  /** Escape hatch: deep-merged into the echarts option the props built. */
929
1110
  echartOptions?: EchartOptionsOverride
930
1111
  }
931
1112
 
1113
+ export type PercentageBarChartProps = ChartBaseProps & {
1114
+ /** The rows to draw. One row is one slice, before the "Others" grouping. */
1115
+ data: Record<string, any>[]
1116
+ /** Row key holding the slice name. */
1117
+ category: string
1118
+ /** Row key holding the slice size. */
1119
+ value: string
1120
+ /**
1121
+ * How many slices the bar holds, "Others" included. Past that the bar keeps
1122
+ * the largest `maxSlices - 1` and sums the tail into a single "Others" slice,
1123
+ * named `OTHERS_KEY`. Defaults to 9, as on `DonutChart`, so a breakdown cuts
1124
+ * into the same slices on either chart.
1125
+ */
1126
+ maxSlices?: number
1127
+ /**
1128
+ * The order the slices go along the bar. `'size'` puts the biggest first.
1129
+ * `'rows'` keeps the rows' order, for categories that already have one, such
1130
+ * as ageing buckets or months. Either way `maxSlices` keeps the largest, and
1131
+ * "Others" comes last. Defaults to `'size'`, as on `DonutChart`.
1132
+ */
1133
+ order?: SliceOrder
1134
+ /**
1135
+ * Slices the legend has switched off, by name. Bind it with
1136
+ * `v-model:hiddenSlices` to drive the legend from the app. Left unbound, the
1137
+ * legend owns it.
1138
+ */
1139
+ hiddenSlices?: string[]
1140
+ /** Prints the tooltip and each slice's accessible name. */
1141
+ format?: ChartValueFormatter
1142
+ /** Defaults to `'categorical'`: slices are unrelated categories, not steps. */
1143
+ palette?: ChartPalette
1144
+ /**
1145
+ * Pins a color to a slice, keyed by its category value, e.g. `{ Overdue:
1146
+ * 'var(--ink-red-5)' }`. `OTHERS_KEY` pins "Others". A category grouped into
1147
+ * "Others" takes that slice's color. The other slices keep the palette color
1148
+ * they would have had.
1149
+ */
1150
+ colors?: Record<string, string>
1151
+ }
1152
+
932
1153
  export type FunnelChartProps = ChartBaseProps & {
933
1154
  /** One row per stage, in process order. Rows are drawn as they arrive. */
934
1155
  data: Record<string, any>[]
@@ -951,7 +1172,10 @@ export type HeatmapChartProps = ChartBaseProps & {
951
1172
  y: string
952
1173
  /** Row key holding the magnitude the cell is colored by. */
953
1174
  value: string
954
- /** Bottom of the color scale. Defaults to the smallest value in the data. */
1175
+ /**
1176
+ * Bottom of the color scale. Defaults to 0 when no value is negative, else to
1177
+ * the smallest value in the data.
1178
+ */
955
1179
  min?: number
956
1180
  /** Top of the color scale. Defaults to the largest value in the data. */
957
1181
  max?: number
@@ -975,6 +1199,50 @@ export type HeatmapChartProps = ChartBaseProps & {
975
1199
  echartOptions?: EchartOptionsOverride
976
1200
  }
977
1201
 
1202
+ export type CalendarHeatmapChartProps = ChartBaseProps & {
1203
+ /** The rows to plot, one per day. Of two on the same day, the later one is drawn. */
1204
+ data: Record<string, any>[]
1205
+ /**
1206
+ * Row key holding the day: a `Date`, or an ISO string such as `2024-03-01`.
1207
+ * A time or offset after the date is ignored.
1208
+ */
1209
+ date: string
1210
+ /** Row key holding the magnitude the day is colored by. */
1211
+ value: string
1212
+ /**
1213
+ * First day drawn, as a `Date` or an ISO string. Defaults to the first of the
1214
+ * month the data starts in. Given with `end`, the range is drawn even with no
1215
+ * data in it.
1216
+ */
1217
+ start?: string | Date
1218
+ /** Last day drawn. Defaults to the last of the month the data ends in. */
1219
+ end?: string | Date
1220
+ /**
1221
+ * The weekday at the top of each column. Defaults to the week start of the
1222
+ * dayjs locale, and to `'sunday'` when the locale names none.
1223
+ */
1224
+ weekStart?: CalendarHeatmapWeekStart
1225
+ /**
1226
+ * Bottom of the color scale. Defaults to 0 when no day is negative, else to
1227
+ * the smallest day in the range.
1228
+ */
1229
+ min?: number
1230
+ /**
1231
+ * Top of the color scale. Defaults to the largest day in the range. Days
1232
+ * above it draw in the deepest color, and the scale reads `≥ max`.
1233
+ */
1234
+ max?: number
1235
+ /** Prints every number the calendar shows: the scale ends and the tooltip. */
1236
+ format?: ChartValueFormatter
1237
+ /**
1238
+ * Ramp days are colored from. Defaults to `'sequential'`; `'diverging'` is
1239
+ * for signed data and centers on zero.
1240
+ */
1241
+ palette?: HeatmapPalette
1242
+ /** Escape hatch: deep-merged into the echarts option the props built. */
1243
+ echartOptions?: EchartOptionsOverride
1244
+ }
1245
+
978
1246
  export type SankeyChartProps = ChartBaseProps & {
979
1247
  /** One row per flow, i.e. one band from a source node to a target node. */
980
1248
  data: Record<string, any>[]
@@ -1081,6 +1349,8 @@ export type NumberCardProps = Omit<ChartBaseProps, 'subtitle'> &
1081
1349
  deltaFormat?: ChartValueFormatter
1082
1350
  /** A trend across the bottom of the card: shape only, no axes to read against. */
1083
1351
  sparkline?: NumberCardSparkline
1352
+ /** How far the reading has come towards a whole, drawn as a bar under it and its change. */
1353
+ progress?: NumberCardProgress
1084
1354
  }
1085
1355
 
1086
1356
  // The chrome, i.e. everything around the plot. A chart an app draws itself
@@ -1117,12 +1387,20 @@ export type ChartContainerProps = {
1117
1387
  error?: string | null
1118
1388
  /** Draws the empty state: there is data, and it plots to nothing. */
1119
1389
  empty?: boolean
1390
+ /**
1391
+ * Centres the plot and its legend in the height the card has to spare, for
1392
+ * a plot as tall as its content. Otherwise the plot takes that height.
1393
+ */
1394
+ centered?: boolean
1120
1395
  /** Forces layout direction; defaults to document.documentElement.dir */
1121
1396
  dir?: ChartDir
1122
1397
  }
1123
1398
 
1124
1399
  export type ChartLegendProps = {
1125
- /** One entry per series, in the order they are drawn. */
1400
+ /**
1401
+ * One entry per series, in the order they are drawn. Entries that do not fit
1402
+ * on one row go behind "+N more", ranked by `weight`.
1403
+ */
1126
1404
  items: ChartLegendItem[]
1127
1405
  }
1128
1406
 
@@ -1246,6 +1524,19 @@ export type DonutChartSlots = ChartActionsSlot &
1246
1524
  tooltip?: (props: ChartTooltipSlotProps) => unknown
1247
1525
  }
1248
1526
 
1527
+ /** The ring's events: the bar cuts the same slices. */
1528
+ export type PercentageBarChartEmits = DonutChartEmits
1529
+
1530
+ export type PercentageBarChartSlots = ChartActionsSlot &
1531
+ ChartTitleSuffixSlot &
1532
+ ChartStateSlots & {
1533
+ /**
1534
+ * Replaces the tooltip body. `items` holds the hovered slice alone. A named
1535
+ * slice carries one row, and the "Others" slice every row it collapsed.
1536
+ */
1537
+ tooltip?: (props: ChartTooltipSlotProps) => unknown
1538
+ }
1539
+
1249
1540
  export type FunnelChartEmits = {
1250
1541
  /**
1251
1542
  * A stage was selected, by click or by Enter on the keyboard cursor. Carries
@@ -1284,6 +1575,24 @@ export type HeatmapChartSlots = ChartActionsSlot &
1284
1575
  tooltip?: (props: ChartTooltipSlotProps) => unknown
1285
1576
  }
1286
1577
 
1578
+ export type CalendarHeatmapChartEmits = {
1579
+ /**
1580
+ * A day with data was selected, by click or by Enter on the keyboard cursor.
1581
+ * Carries the day, its value and the row behind it.
1582
+ */
1583
+ select: [event: CalendarHeatmapCellEvent]
1584
+ }
1585
+
1586
+ export type CalendarHeatmapChartSlots = ChartActionsSlot &
1587
+ ChartTitleSuffixSlot &
1588
+ ChartStateSlots & {
1589
+ /**
1590
+ * Replaces the tooltip body. `items` holds the hovered day alone, and
1591
+ * `rows` the row behind it. A day with no row reads `No data`, with no row.
1592
+ */
1593
+ tooltip?: (props: ChartTooltipSlotProps) => unknown
1594
+ }
1595
+
1287
1596
  export type SankeyChartEmits = {
1288
1597
  /**
1289
1598
  * A band was selected, by click or by Enter on the keyboard cursor. Carries
@@ -23,10 +23,26 @@ avatar from the one under it, and a count stands in for the rest.
23
23
 
24
24
  ### Online status
25
25
 
26
- The `#indicator` slot places a dot on the bottom-right corner.
26
+ The `#indicator` slot places a dot on the bottom-right corner. A class on the
27
+ dot sets its color.
28
+
29
+ ```vue
30
+ <Avatar :image :label>
31
+ <template #indicator>
32
+ <span class="block size-full rounded-full bg-surface-green-5" />
33
+ </template>
34
+ </Avatar>
35
+ ```
27
36
 
28
37
  <ComponentPreview name="Avatar-Presence" />
29
38
 
39
+ ### Verified badge
40
+
41
+ The indicator can hold an icon. Use a size with room for it, and give it text
42
+ for screen readers.
43
+
44
+ <ComponentPreview name="Avatar-Verified" />
45
+
30
46
  ### Workspace switcher
31
47
 
32
48
  Square avatars stand for workspaces and teams, round ones for people. The
@@ -53,12 +69,21 @@ initial and its background. It has no effect on a photo.
53
69
 
54
70
  A sizing class on the avatar (`size-*`, `w-*`, `h-*`) replaces the `size`
55
71
  prop's width and height. The `size` prop still sets the text size of the
56
- initial and the size of the indicator dot. A responsive class like
72
+ initial and the size of the indicator. A responsive class like
57
73
  `sm:size-16` works alongside `size`: `size` sets the width on small screens,
58
74
  and the class takes over from its breakpoint up.
59
75
 
76
+ ### Indicator
77
+
78
+ The avatar cuts a circle out of its bottom-right corner for the indicator. The
79
+ gap around the indicator is see-through, so it matches the surface behind the
80
+ avatar, such as a hovered row, a popover or a dialog.
81
+
60
82
  ## Accessibility
61
83
 
62
84
  The image uses `label` as its alt text.
63
85
 
86
+ A status dot shows status with color only. Show the status as text next to the
87
+ avatar, or put text with the `sr-only` class in the indicator.
88
+
64
89
  <!-- @include: ./Avatar.api.md -->
@@ -8,12 +8,14 @@
8
8
  :src="image"
9
9
  :alt="label"
10
10
  :class="[shapeClasses, 'h-full w-full object-cover']"
11
+ :style="$slots.indicator && indicatorMask"
11
12
  @error="(err) => handleImageError(err)"
12
13
  />
13
14
  <div
14
15
  v-else
15
16
  class="flex h-full w-full items-center justify-center uppercase select-none"
16
17
  :class="[labelClasses, fallbackThemeClasses, shapeClasses]"
18
+ :style="$slots.indicator && indicatorMask"
17
19
  >
18
20
  <div :class="iconClasses" v-if="$slots.default">
19
21
  <slot></slot>
@@ -24,10 +26,13 @@
24
26
  </div>
25
27
  <div
26
28
  v-if="$slots.indicator"
27
- :class="[
28
- 'absolute bottom-0 right-0 grid place-items-center rounded-full bg-surface-base',
29
- indicatorContainerClasses,
30
- ]"
29
+ class="absolute grid place-items-center"
30
+ :style="{
31
+ width: indicatorBox.size,
32
+ height: indicatorBox.size,
33
+ right: `-${indicatorBox.offset}`,
34
+ bottom: `-${indicatorBox.offset}`,
35
+ }"
31
36
  >
32
37
  <div :class="indicatorClasses">
33
38
  <slot name="indicator"></slot>
@@ -127,18 +132,30 @@ const labelClasses = computed(() => {
127
132
  return ['font-medium', sizeClass]
128
133
  })
129
134
 
130
- const indicatorContainerClasses = computed(() => {
135
+ // The box the indicator sits in, and how far it hangs past the avatar's
136
+ // bottom-right corner. The avatar masks out a circle the size of this box, so
137
+ // the gap around the indicator shows whatever is behind the avatar.
138
+ const indicatorBox = computed(() => {
131
139
  return {
132
- xs: '-mr-[.1rem] -mb-[.1rem] h-2 w-2',
133
- sm: '-mr-[.1rem] -mb-[.1rem] h-[9px] w-[9px]',
134
- md: '-mr-[.1rem] -mb-[.1rem] h-2.5 w-2.5',
135
- lg: '-mr-[.1rem] -mb-[.1rem] h-3 w-3',
136
- xl: '-mr-[.1rem] -mb-[.1rem] h-3 w-3',
137
- '2xl': '-mr-[.1rem] -mb-[.1rem] h-3.5 w-3.5',
138
- '3xl': '-mr-[.2rem] -mb-[.2rem] h-4 w-4',
140
+ xs: { size: '0.5rem', offset: '0.1rem' },
141
+ sm: { size: '9px', offset: '0.1rem' },
142
+ md: { size: '0.625rem', offset: '0.1rem' },
143
+ lg: { size: '0.75rem', offset: '0.1rem' },
144
+ xl: { size: '0.75rem', offset: '0.1rem' },
145
+ '2xl': { size: '0.875rem', offset: '0.1rem' },
146
+ '3xl': { size: '1rem', offset: '0.2rem' },
139
147
  }[props.size]
140
148
  })
141
149
 
150
+ const indicatorMask = computed(() => {
151
+ const { size, offset } = indicatorBox.value
152
+ const radius = `calc(${size} / 2)`
153
+ const center = `calc(100% - ${radius} + ${offset})`
154
+ return {
155
+ maskImage: `radial-gradient(circle at ${center} ${center}, transparent ${radius}, #000 calc(${radius} + 0.5px))`,
156
+ }
157
+ })
158
+
142
159
  const indicatorClasses = computed(() => {
143
160
  return {
144
161
  xs: 'h-1 w-1',
@@ -39,7 +39,7 @@
39
39
  </router-link>
40
40
  <a
41
41
  v-else-if="item.href"
42
- :href="item.href"
42
+ :href="safeHref(item.href)"
43
43
  @click="onLinkClick(item, $event)"
44
44
  class="flex items-center rounded-4 px-0.5 py-1 text-lg-medium leading-tighter"
45
45
  :class="[
@@ -93,6 +93,7 @@ import { useRouter } from 'vue-router'
93
93
  import { Dropdown } from '../Dropdown'
94
94
  import { Button } from '../Button'
95
95
  import type { BreadcrumbsProps } from './types'
96
+ import { safeHref } from '../../utils/url-safety'
96
97
  import { ref, computed, nextTick, useTemplateRef } from 'vue'
97
98
  import { useResizeObserver } from '@vueuse/core'
98
99
  import type { BreadcrumbItem } from './types'
@@ -196,6 +196,13 @@ const displayValue = computed(() => {
196
196
  return currentValue.value === null ? '' : String(currentValue.value)
197
197
  })
198
198
 
199
+ // The button trigger shows the placeholder when the model is `null`, or `''`
200
+ // with no `''` option to name it. A value that is not in the loaded options
201
+ // shows as text, the same as in input mode.
202
+ const showsPlaceholder = computed(
203
+ () => !selectedOption.value && displayValue.value === '',
204
+ )
205
+
199
206
  const triggerClasses = computed(() => [
200
207
  triggerBaseClasses,
201
208
  triggerSizeClasses(props.size),
@@ -614,10 +621,10 @@ defineSlots<ComboboxSlots>()
614
621
  <span
615
622
  :class="[
616
623
  'min-w-0 flex-1 truncate text-left font-normal leading-tighter',
617
- !selectedOption && 'text-ink-gray-4',
624
+ showsPlaceholder && 'text-ink-gray-4',
618
625
  ]"
619
626
  >
620
- {{ selectedOption?.label ?? placeholder }}
627
+ {{ showsPlaceholder ? placeholder : displayValue }}
621
628
  </span>
622
629
 
623
630
  <slot name="suffix" v-bind="controlSlotProps">
@@ -18,6 +18,7 @@ import type {
18
18
  } from './types'
19
19
  import {
20
20
  EMPTY_SELECTABLE_VALUE_PREFIX,
21
+ checkedItemClasses,
21
22
  isCustomOption,
22
23
  isSelectableOption,
23
24
  itemClasses,
@@ -168,7 +169,11 @@ function handleSelect(item: NormalizedItem, event: Event) {
168
169
  : 'unchecked'
169
170
  : undefined
170
171
  "
171
- :class="[itemClasses, itemRootSizeClasses(size)]"
172
+ :class="[
173
+ itemClasses,
174
+ checkedItemClasses,
175
+ itemRootSizeClasses(size),
176
+ ]"
172
177
  @select="handleSelect(item, $event)"
173
178
  >
174
179
  <!--
@@ -15,6 +15,7 @@ import type {
15
15
  } from './types'
16
16
 
17
17
  export {
18
+ checkedItemClasses,
18
19
  inputFontSizeClasses,
19
20
  itemClasses,
20
21
  itemRootSizeClasses,
@@ -201,4 +202,4 @@ export function buildCustomOptionContext(
201
202
  }
202
203
 
203
204
  export const inputClasses =
204
- 'min-w-0 flex-1 border-0 bg-transparent p-0 text-ink-gray-8 outline-none ring-0 placeholder:text-ink-gray-4 focus:border-0 focus:outline-none focus:ring-0'
205
+ 'min-w-0 flex-1 border-0 bg-transparent p-0 text-ink-gray-8 disabled:text-ink-gray-4 outline-none ring-0 placeholder:text-ink-gray-4 focus:border-0 focus:outline-none focus:ring-0'