@cloudflare/kumo 2.7.0 → 2.8.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 (62) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/ai/component-registry.json +1164 -149
  3. package/ai/component-registry.md +1325 -114
  4. package/ai/schemas.ts +136 -7
  5. package/dist/.build-complete +1 -1
  6. package/dist/ai/schemas.d.ts +259 -22
  7. package/dist/ai/schemas.d.ts.map +1 -1
  8. package/dist/ai/schemas.js +1515 -1298
  9. package/dist/ai/schemas.js.map +1 -1
  10. package/dist/chunks/Maps-imwfwgb7do9lr3i5.js +2448 -0
  11. package/dist/chunks/Maps-imwfwgb7do9lr3i5.js.map +1 -0
  12. package/dist/chunks/input-area-sg518xu4pyg4m0km.js +144 -0
  13. package/dist/chunks/input-area-sg518xu4pyg4m0km.js.map +1 -0
  14. package/dist/chunks/{sidebar-ctd980heycmxsux1.js → sidebar-7whsl7qwrw5b6ip8.js} +306 -306
  15. package/dist/chunks/sidebar-7whsl7qwrw5b6ip8.js.map +1 -0
  16. package/dist/components/chart.js +1 -1
  17. package/dist/components/flow.js +2306 -2350
  18. package/dist/components/flow.js.map +1 -1
  19. package/dist/components/input.js +1 -1
  20. package/dist/components/sidebar.js +1 -1
  21. package/dist/index.js +3 -3
  22. package/dist/src/components/chart/TimeseriesChart.d.ts +8 -0
  23. package/dist/src/components/chart/TimeseriesChart.d.ts.map +1 -1
  24. package/dist/src/components/chart/index.d.ts +1 -1
  25. package/dist/src/components/chart/index.d.ts.map +1 -1
  26. package/dist/src/components/chart/timeseries-markers.d.ts +107 -0
  27. package/dist/src/components/chart/timeseries-markers.d.ts.map +1 -0
  28. package/dist/src/components/chart/timeseries-thresholds.d.ts +61 -0
  29. package/dist/src/components/chart/timeseries-thresholds.d.ts.map +1 -0
  30. package/dist/src/components/chart/timeseries-tooltip.d.ts +28 -0
  31. package/dist/src/components/chart/timeseries-tooltip.d.ts.map +1 -0
  32. package/dist/src/components/flow/connectors.d.ts +18 -0
  33. package/dist/src/components/flow/connectors.d.ts.map +1 -1
  34. package/dist/src/components/flow/diagram.d.ts +48 -41
  35. package/dist/src/components/flow/diagram.d.ts.map +1 -1
  36. package/dist/src/components/flow/flow-layout.d.ts +77 -0
  37. package/dist/src/components/flow/flow-layout.d.ts.map +1 -0
  38. package/dist/src/components/flow/node.d.ts.map +1 -1
  39. package/dist/src/components/flow/parallel.d.ts +3 -7
  40. package/dist/src/components/flow/parallel.d.ts.map +1 -1
  41. package/dist/src/components/flow/use-children.d.ts +0 -60
  42. package/dist/src/components/flow/use-children.d.ts.map +1 -1
  43. package/dist/src/components/input/input-area.d.ts +18 -0
  44. package/dist/src/components/input/input-area.d.ts.map +1 -1
  45. package/dist/src/components/sidebar/sidebar.d.ts +2 -0
  46. package/dist/src/components/sidebar/sidebar.d.ts.map +1 -1
  47. package/dist/src/primitives/index.d.ts +1 -1
  48. package/dist/src/primitives/index.d.ts.map +1 -1
  49. package/dist/src/primitives/otp-field.d.ts +1 -1
  50. package/dist/src/primitives/otp-field.d.ts.map +1 -1
  51. package/dist/styles/kumo-standalone.css +1 -1
  52. package/package.json +1 -1
  53. package/scripts/component-registry/discovery.ts +87 -0
  54. package/scripts/component-registry/index.test.ts +89 -1
  55. package/scripts/component-registry/index.ts +27 -2
  56. package/scripts/component-registry/sub-components.ts +34 -21
  57. package/scripts/generate-primitives.ts +1 -1
  58. package/dist/chunks/Maps-fkiyllhs5w0qzw1y.js +0 -2155
  59. package/dist/chunks/Maps-fkiyllhs5w0qzw1y.js.map +0 -1
  60. package/dist/chunks/input-area-ixtj4e8eny58nbf9.js +0 -78
  61. package/dist/chunks/input-area-ixtj4e8eny58nbf9.js.map +0 -1
  62. package/dist/chunks/sidebar-ctd980heycmxsux1.js.map +0 -1
@@ -596,6 +596,120 @@ Props:
596
596
  ```
597
597
 
598
598
 
599
+ ---
600
+
601
+ ### BubbleMap
602
+
603
+ BubbleMap component
604
+
605
+ **Type:** component
606
+
607
+ **Import:** `import { BubbleMap } from "@cloudflare/kumo";`
608
+
609
+ **Category:** Data Visualization
610
+
611
+ **Props:**
612
+
613
+ - `echarts`: typeof echarts (required)
614
+ The ECharts core instance imported by the consumer (passed in for tree-shaking). Requires `MapChart`, `ScatterChart`, `TooltipComponent`, and a renderer registered via `echarts.use([...])`.
615
+ - `geoJson`: MapGeoJson (required)
616
+ GeoJSON `FeatureCollection` for the land base.
617
+ - `mapName`: string
618
+ Optional stable ECharts map registry name. Set this when the same GeoJSON is parsed into new object instances across mounts and should reuse one global ECharts registration.
619
+ - `data`: T[] (required)
620
+ Raw data rows. Coordinates/value/name are read via the accessors below.
621
+ - `lng`: MapAccessor<T, number> (required)
622
+ Longitude accessor (key of `T` or `(row) => number`).
623
+ - `lat`: MapAccessor<T, number> (required)
624
+ Latitude accessor (key of `T` or `(row) => number`).
625
+ - `value`: MapAccessor<T, number> (required)
626
+ Value accessor — drives bubble size.
627
+ - `name`: MapAccessor<T, string>
628
+ Optional name accessor — used by the default tooltip.
629
+ - `minRadius`: number
630
+ Smallest bubble radius in px. Default: `6`.
631
+ - `maxRadius`: number
632
+ Largest bubble radius in px. Default: `26`.
633
+ - `bubbleSize`: (value: number) => number
634
+ Explicit bubble radius `(value) => px`. Overrides the default `minRadius`/`maxRadius` scaling.
635
+ - `bubbleColor`: MapStyle<T, string>
636
+ Bubble fill colour — constant or `(row) => color`. Defaults to the chart blue.
637
+ - `bubbleBorderColor`: MapStyle<T, string>
638
+ Bubble border colour — constant or `(row) => color`. Default: `transparent`.
639
+ - `bubbleBorderWidth`: MapStyle<T, number>
640
+ Bubble border width — constant or `(row) => px`. Default: `0`.
641
+ - `center`: [number, number]
642
+ Map center as `[longitude, latitude]`. Defaults to auto-fit.
643
+ - `zoom`: number
644
+ Zoom level — multiplies the auto-fit scale. Default: `1.25`.
645
+ - `roam`: boolean
646
+ Enable drag-to-pan and scroll-to-zoom. Default: `false`.
647
+ - `projection`: MapProjection | null
648
+ Geographic projection. Defaults to a latitude-clamped Mercator (flat 2D web-map look). Pass another d3-geo projection to override, or `null` for ECharts' raw equirectangular plotting. Use a stable reference (module-level or memoised): a new object each render rebuilds the view and resets a roamed/zoomed map.
649
+ - `showTooltip`: boolean
650
+ Show the tooltip. Default: `true`.
651
+ - `valueFormat`: (value: number) => string
652
+ Format the value for the default tooltip. Default: `toLocaleString()`.
653
+ - `tooltipFormatter`: (row: T) => string
654
+ Override the tooltip content for a row. Returns an HTML string rendered by ECharts' own tooltip. USE WITH CAUTION: the return value is injected as HTML. Escape any user-provided strings to avoid XSS.
655
+ - `aspectRatio`: number | string
656
+ Container aspect ratio as `width / height` (e.g. `1.7` or `"16 / 9"`). The height derives from the rendered width so the map fills the frame with no letterboxing. Defaults to the projected aspect of the displayed window, so the land fits edge-to-edge. Pass `height` to fix a pixel height instead.
657
+ - `height`: number
658
+ Fixed chart height in pixels. Overrides `aspectRatio` when set. Leave unset to size by aspect ratio (the default) so the map fills the container.
659
+ - `className`: string
660
+ - `isDarkMode`: boolean
661
+
662
+ **Examples:**
663
+
664
+ ```tsx
665
+ <BubbleMap<CfLocation>
666
+ echarts={echarts}
667
+ geoJson={geoJson}
668
+ data={cloudflareLocations}
669
+ lng="lon"
670
+ lat="lat"
671
+ name="city"
672
+ value={() => 1}
673
+ bubbleColor="#F6821F"
674
+ minRadius={8}
675
+ maxRadius={8}
676
+ tooltipFormatter={(row) =>
677
+ `<span style="font-size:12px"><strong>${row.city}</strong><span style="color:var(--text-color-kumo-subtle);margin-left:8px">${row.iata}</span></span>`
678
+ }
679
+ isDarkMode={isDarkMode}
680
+ />
681
+ ```
682
+
683
+ ```tsx
684
+ <BubbleMap<Colo>
685
+ echarts={echarts}
686
+ geoJson={geoJson}
687
+ data={colos}
688
+ lng="lon"
689
+ lat="lat"
690
+ name="city"
691
+ value="requests"
692
+ valueFormat={fmt}
693
+ minRadius={8}
694
+ isDarkMode={isDarkMode}
695
+ />
696
+ ```
697
+
698
+ ```tsx
699
+ <BubbleMap<Colo>
700
+ echarts={echarts}
701
+ geoJson={geoJson}
702
+ data={colos2}
703
+ lng="lon"
704
+ lat="lat"
705
+ name="city"
706
+ value="requests"
707
+ valueFormat={fmt}
708
+ isDarkMode={isDarkMode}
709
+ />
710
+ ```
711
+
712
+
599
713
  ---
600
714
 
601
715
  ### Button
@@ -740,6 +854,376 @@ Primary action trigger. Supports multiple variants, sizes, shapes, icons, and lo
740
854
  ```
741
855
 
742
856
 
857
+ ---
858
+
859
+ ### Chart
860
+
861
+ Chart — a low-level wrapper around [Apache ECharts](https://echarts.apache.org).
862
+
863
+ **Type:** component
864
+
865
+ **Import:** `import { Chart } from "@cloudflare/kumo";`
866
+
867
+ **Category:** Data Visualization
868
+
869
+ **Props:**
870
+
871
+ - `echarts`: typeof echarts (required)
872
+ The ECharts core instance imported by the consumer. Passed in rather than imported directly so the consumer controls which ECharts modules are bundled (tree-shaking).
873
+ - `options`: KumoChartOption (required)
874
+ ECharts option object — passed through to `chart.setOption()`
875
+ - `optionUpdateBehavior`: SetOptionOpts
876
+ Additional options passed as the second argument to `chart.setOption()`. Defaults to `{ notMerge: false, lazyUpdate: true }`.
877
+ - `className`: string
878
+ Additional CSS classes applied to the chart container `<div>`
879
+ - `isDarkMode`: boolean
880
+ When `true`, initialises ECharts with its built-in dark theme. Changing this value after mount destroys and re-creates the chart instance.
881
+ - `height`: number
882
+ Height of the chart container in pixels. Defaults to `350`.
883
+ - `aspectRatio`: number | string
884
+ Container aspect ratio as `width / height` (e.g. `1.7` or `"16 / 9"`). When set, the height derives from the rendered width via CSS `aspect-ratio` and the `height` prop is ignored — useful for maps so the canvas matches the map's shape and fills the frame with no letterboxing.
885
+
886
+ **Examples:**
887
+
888
+ ```tsx
889
+ <Chart
890
+ echarts={echarts}
891
+ options={options}
892
+ height={400}
893
+ isDarkMode={isDarkMode}
894
+ />
895
+ ```
896
+
897
+ ```tsx
898
+ <TimeseriesChart
899
+ echarts={echarts}
900
+ isDarkMode={isDarkMode}
901
+ data={data}
902
+ xAxisName="Time (UTC)"
903
+ yAxisName="Count"
904
+ />
905
+ ```
906
+
907
+ ```tsx
908
+ <TimeseriesChart
909
+ echarts={echarts}
910
+ isDarkMode={isDarkMode}
911
+ data={data}
912
+ markers={markers}
913
+ xAxisName="Time (UTC)"
914
+ yAxisName="Count"
915
+ />
916
+ ```
917
+
918
+ ```tsx
919
+ <TimeseriesChart
920
+ echarts={echarts}
921
+ isDarkMode={isDarkMode}
922
+ data={data}
923
+ thresholds={[
924
+ {
925
+ value: 55,
926
+ label: "Memory limit",
927
+ color: ChartPalette.semantic("Attention", isDarkMode),
928
+ },
929
+ ]}
930
+ xAxisName="Time (UTC)"
931
+ yAxisName="Memory (MB)"
932
+ />
933
+ ```
934
+
935
+ ```tsx
936
+ <TimeseriesChart
937
+ echarts={echarts}
938
+ isDarkMode={isDarkMode}
939
+ data={data}
940
+ xAxisName="Time (UTC)"
941
+ yAxisName="Requests"
942
+ xAxisTickFormat={(ts) => {
943
+ const d = new Date(ts);
944
+ return `${d.getHours().toString().padStart(2, "0")}:${d.getMinutes().toString().padStart(2, "0")}`;
945
+ }}
946
+ yAxisTickFormat={(value) => {
947
+ if (value >= 1000) return `${value / 1000}k`;
948
+ return value.toString();
949
+ }}
950
+ tooltipValueFormat={(value) => `${(value / 1000).toFixed(1)}k requests`}
951
+ />
952
+ ```
953
+
954
+ ```tsx
955
+ <TimeseriesChart
956
+ yAxisTickCount={2}
957
+ echarts={echarts}
958
+ isDarkMode={isDarkMode}
959
+ data={data}
960
+ height={160}
961
+ />
962
+ ```
963
+
964
+ ```tsx
965
+ <TimeseriesChart
966
+ echarts={echarts}
967
+ isDarkMode={isDarkMode}
968
+ data={data}
969
+ xAxisName="Time (UTC)"
970
+ yAxisName="Mbps"
971
+ incomplete={{ after: incompleteTimestamp }}
972
+ />
973
+ ```
974
+
975
+ ```tsx
976
+ <TimeseriesChart
977
+ echarts={echarts}
978
+ isDarkMode={isDarkMode}
979
+ data={data}
980
+ xAxisName="Time (UTC)"
981
+ yAxisName="%"
982
+ onTimeRangeChange={(from, to) => {
983
+ alert(
984
+ `Selected range:\nFrom: ${new Date(from).toLocaleString()}\nTo: ${new Date(to).toLocaleString()}`,
985
+ );
986
+ }}
987
+ />
988
+ ```
989
+
990
+ ```tsx
991
+ <div className="space-y-4">
992
+ <h3 className="text-sm font-medium">Active State</h3>
993
+
994
+ <div className="flex flex-wrap gap-4 divide-x divide-kumo-hairline">
995
+ <ChartLegend.LargeItem
996
+ name="Requests"
997
+ color={ChartPalette.semantic("Neutral", isDarkMode)}
998
+ value="1,234"
999
+ unit="req/s"
1000
+ />
1001
+ <ChartLegend.LargeItem
1002
+ name="Storage"
1003
+ color={ChartPalette.semantic("Attention", isDarkMode)}
1004
+ value="56"
1005
+ unit="GB"
1006
+ />
1007
+ <ChartLegend.LargeItem
1008
+ name="Warnings"
1009
+ color={ChartPalette.semantic("Warning", isDarkMode)}
1010
+ value="128"
1011
+ />
1012
+ </div>
1013
+
1014
+ <h3 className="text-sm font-medium mt-12">Inactive State</h3>
1015
+
1016
+ <div className="flex flex-wrap gap-4 divide-x divide-kumo-hairline">
1017
+ <ChartLegend.LargeItem
1018
+ name="Requests"
1019
+ color={ChartPalette.semantic("Neutral", isDarkMode)}
1020
+ value="1,234"
1021
+ unit="req/s"
1022
+ inactive
1023
+ />
1024
+ <ChartLegend.LargeItem
1025
+ name="Storage"
1026
+ color={ChartPalette.semantic("Attention", isDarkMode)}
1027
+ value="56"
1028
+ unit="GB"
1029
+ inactive
1030
+ />
1031
+ <ChartLegend.LargeItem
1032
+ name="Warnings"
1033
+ color={ChartPalette.semantic("Warning", isDarkMode)}
1034
+ value="128"
1035
+ inactive
1036
+ />
1037
+ </div>
1038
+ </div>
1039
+ ```
1040
+
1041
+ ```tsx
1042
+ <TimeseriesChart
1043
+ echarts={echarts}
1044
+ isDarkMode={isDarkMode}
1045
+ type="bar"
1046
+ data={data}
1047
+ xAxisName="Time (UTC)"
1048
+ yAxisName="Count"
1049
+ tooltipValueFormat={(r) => r.toFixed(2)}
1050
+ />
1051
+ ```
1052
+
1053
+ ```tsx
1054
+ <div className="flex flex-col flex-1 w-full">
1055
+ <TimeseriesChart
1056
+ echarts={echarts}
1057
+ isDarkMode={isDarkMode}
1058
+ xAxisName="Time (UTC)"
1059
+ yAxisName="Count"
1060
+ data={[]}
1061
+ loading
1062
+ />
1063
+ </div>
1064
+ ```
1065
+
1066
+ ```tsx
1067
+ <LayerCard>
1068
+ <LayerCard.Secondary>Read latency</LayerCard.Secondary>
1069
+ <LayerCard.Primary>
1070
+ <div className="flex divide-x divide-kumo-hairline gap-4 px-2 mb-2">
1071
+ <ChartLegend.LargeItem
1072
+ name="P99"
1073
+ color={ChartPalette.semantic("Attention", isDarkMode)}
1074
+ value="124"
1075
+ unit="ms"
1076
+ />
1077
+ <ChartLegend.LargeItem
1078
+ name="P95"
1079
+ color={ChartPalette.semantic("Warning", isDarkMode)}
1080
+ value="76"
1081
+ unit="ms"
1082
+ />
1083
+ <ChartLegend.LargeItem
1084
+ name="P75"
1085
+ color={ChartPalette.semantic("Neutral", isDarkMode)}
1086
+ value="32"
1087
+ unit="ms"
1088
+ />
1089
+ <ChartLegend.LargeItem
1090
+ name="P50"
1091
+ color={ChartPalette.semantic("Neutral", isDarkMode)}
1092
+ value="10"
1093
+ unit="ms"
1094
+ />
1095
+ </div>
1096
+ <TimeseriesChart
1097
+ xAxisName="Time (UTC)"
1098
+ echarts={echarts}
1099
+ isDarkMode={isDarkMode}
1100
+ data={data}
1101
+ height={300}
1102
+ />
1103
+ </LayerCard.Primary>
1104
+ </LayerCard>
1105
+ ```
1106
+
1107
+ ```tsx
1108
+ <LayerCard>
1109
+ <LayerCard.Secondary>Read latency</LayerCard.Secondary>
1110
+ <LayerCard.Primary>
1111
+ <div className="flex divide-x divide-kumo-line px-2 mb-2">
1112
+ {series.map((s) => (
1113
+ <ChartLegend.LargeItem
1114
+ key={s.name}
1115
+ name={s.name}
1116
+ color={s.color}
1117
+ value={s.value}
1118
+ unit={s.unit}
1119
+ inactive={hoveredSeries !== null && hoveredSeries !== s.name}
1120
+ onPointerEnter={() => {
1121
+ setHoveredSeries(s.name);
1122
+ chartRef.current?.dispatchAction({
1123
+ type: "highlight",
1124
+ seriesName: s.name,
1125
+ });
1126
+ }}
1127
+ onPointerLeave={() => {
1128
+ setHoveredSeries(null);
1129
+ chartRef.current?.dispatchAction({
1130
+ type: "downplay",
1131
+ seriesName: s.name,
1132
+ });
1133
+ }}
1134
+ className="not-first:pl-4"
1135
+ />
1136
+ ))}
1137
+ </div>
1138
+ <TimeseriesChart
1139
+ ref={chartRef}
1140
+ xAxisName="Time (UTC)"
1141
+ echarts={echarts}
1142
+ isDarkMode={isDarkMode}
1143
+ data={data}
1144
+ height={300}
1145
+ />
1146
+ </LayerCard.Primary>
1147
+ </LayerCard>
1148
+ ```
1149
+
1150
+ ```tsx
1151
+ <LayerCard>
1152
+ <LayerCard.Secondary>Read latency</LayerCard.Secondary>
1153
+ <LayerCard.Primary>
1154
+ <div className="flex divide-x divide-kumo-line px-2 mb-2">
1155
+ {series.map((s) => (
1156
+ <ChartLegend.LargeItem
1157
+ key={s.name}
1158
+ name={s.name}
1159
+ color={s.color}
1160
+ value={s.value}
1161
+ unit={s.unit}
1162
+ inactive={hiddenSeries[s.name] ?? false}
1163
+ onClick={() => handleClick(s.name)}
1164
+ className="not-first:pl-4"
1165
+ />
1166
+ ))}
1167
+ </div>
1168
+ <TimeseriesChart
1169
+ ref={chartRef}
1170
+ xAxisName="Time (UTC)"
1171
+ echarts={echarts}
1172
+ isDarkMode={isDarkMode}
1173
+ data={data}
1174
+ height={300}
1175
+ enableLegendSelection
1176
+ />
1177
+ </LayerCard.Primary>
1178
+ </LayerCard>
1179
+ ```
1180
+
1181
+ ```tsx
1182
+ <div className="flex w-full flex-col gap-4">
1183
+ <Select
1184
+ label="Tooltip follow cursor"
1185
+ value={selected}
1186
+ onValueChange={(v) => {
1187
+ if (v) setSelected(v);
1188
+ }}
1189
+ renderValue={(v) => v.label}
1190
+ >
1191
+ {FOLLOW_CURSOR_OPTIONS.map((opt) => (
1192
+ <Select.Option key={opt.value} value={opt}>
1193
+ {opt.label}
1194
+ </Select.Option>
1195
+ ))}
1196
+ </Select>
1197
+ <TimeseriesChart
1198
+ echarts={echarts}
1199
+ isDarkMode={isDarkMode}
1200
+ data={data}
1201
+ xAxisName="Time (UTC)"
1202
+ yAxisName="Latency (ms)"
1203
+ tooltipFollowCursor={selected.value}
1204
+ />
1205
+ </div>
1206
+ ```
1207
+
1208
+ ```tsx
1209
+ <div
1210
+ ref={boundaryRef}
1211
+ className="w-full overflow-auto rounded-lg border border-kumo-line"
1212
+ style={{ height: 300 }}
1213
+ >
1214
+ <TimeseriesChart
1215
+ echarts={echarts}
1216
+ isDarkMode={isDarkMode}
1217
+ data={data}
1218
+ xAxisName="Time (UTC)"
1219
+ yAxisName="Count"
1220
+ height={280}
1221
+ tooltipBoundary={boundary ?? undefined}
1222
+ />
1223
+ </div>
1224
+ ```
1225
+
1226
+
743
1227
  ---
744
1228
 
745
1229
  ### Checkbox
@@ -814,23 +1298,23 @@ Item sub-component
814
1298
  Group sub-component
815
1299
 
816
1300
  Props:
817
- - `legend`: string
818
- - `children`: ReactNode (required)
819
- - `error`: string
820
- - `description`: ReactNode
821
- - `value`: string[]
822
- - `allValues`: string[]
823
- - `disabled`: boolean
824
- - `controlFirst`: boolean
825
- - `className`: string
1301
+ - `legend`: string - Legend text for the group. For more control over legend styling, omit this prop and use `<Checkbox.Legend>` as a child instead.
1302
+ - `children`: ReactNode (required) - Child Checkbox.Item components (and optionally a Checkbox.Legend)
1303
+ - `error`: string - Error message for the group (only appears in groups, not single checkboxes)
1304
+ - `description`: ReactNode - Helper text for the group
1305
+ - `value`: string[] - Values of checkboxes that should be checked (controlled)
1306
+ - `allValues`: string[] - All possible checkbox values (required for parent checkbox pattern)
1307
+ - `disabled`: boolean - Whether all checkboxes in the group are disabled
1308
+ - `controlFirst`: boolean - When true (default), checkbox appears before label. When false, label appears before checkbox.
1309
+ - `className`: string - Additional CSS classes
826
1310
 
827
1311
  #### Checkbox.Legend
828
1312
 
829
1313
  Legend sub-component
830
1314
 
831
1315
  Props:
832
- - `children`: ReactNode (required)
833
- - `className`: string
1316
+ - `children`: ReactNode (required) - Legend content
1317
+ - `className`: string - Additional CSS classes (e.g. "sr-only" to visually hide the legend)
834
1318
 
835
1319
 
836
1320
  **Examples:**
@@ -905,6 +1389,76 @@ Props:
905
1389
  ```
906
1390
 
907
1391
 
1392
+ ---
1393
+
1394
+ ### ChoroplethMap
1395
+
1396
+ ChoroplethMap component
1397
+
1398
+ **Type:** component
1399
+
1400
+ **Import:** `import { ChoroplethMap } from "@cloudflare/kumo";`
1401
+
1402
+ **Category:** Data Visualization
1403
+
1404
+ **Props:**
1405
+
1406
+ - `echarts`: typeof echarts (required)
1407
+ The ECharts core instance imported by the consumer (passed in for tree-shaking). Requires `MapChart`, `VisualMapComponent`, `TooltipComponent`, and a renderer registered via `echarts.use([...])`.
1408
+ - `geoJson`: MapGeoJson (required)
1409
+ GeoJSON `FeatureCollection` whose regions are shaded by value.
1410
+ - `mapName`: string
1411
+ Optional stable ECharts map registry name. Set this when the same GeoJSON is parsed into new object instances across mounts and should reuse one global ECharts registration.
1412
+ - `data`: T[] (required)
1413
+ Raw data rows. The region key and value are read via the accessors below.
1414
+ - `name`: MapAccessor<T, string> (required)
1415
+ Region-key accessor (key of `T` or `(row) => string`). Each row is joined to a GeoJSON feature whose `nameProperty` equals this value.
1416
+ - `value`: MapAccessor<T, number> (required)
1417
+ Value accessor — drives the region's fill colour.
1418
+ - `nameProperty`: string
1419
+ GeoJSON feature property to join on. Default: `"name"`. Real-world data is often more reliably matched on an ISO-code property (e.g. `"iso_a2"`).
1420
+ - `colorRange`: string[]
1421
+ Sequential colour ramp (low → high). Defaults to the Kumo choropleth blues, tuned to stay distinct from the no-data fill. Distributed across the continuous gradient.
1422
+ - `noDataColor`: string
1423
+ Fill for regions with no matching data row. Defaults to the neutral land grey.
1424
+ - `showLegend`: boolean
1425
+ Show the visualMap colour legend. Default: `false`.
1426
+ - `showTooltip`: boolean
1427
+ Show the tooltip. Default: `true`.
1428
+ - `valueFormat`: (value: number) => string
1429
+ Format the value for the default tooltip. Default: `toLocaleString()`.
1430
+ - `tooltipFormatter`: (row: T) => string
1431
+ Override the tooltip content for a row. Returns an HTML string rendered by ECharts' own tooltip. USE WITH CAUTION: the return value is injected as HTML. Escape any user-provided strings to avoid XSS.
1432
+ - `center`: [number, number]
1433
+ Map center as `[longitude, latitude]`. Defaults to auto-fit.
1434
+ - `zoom`: number
1435
+ Zoom level — multiplies the auto-fit scale. Default: `1.25`.
1436
+ - `roam`: boolean
1437
+ Enable drag-to-pan and scroll-to-zoom. Default: `false`.
1438
+ - `projection`: MapProjection | null
1439
+ Geographic projection. Defaults to a latitude-clamped Mercator (flat 2D web-map look). Pass another d3-geo projection to override, or `null` for ECharts' raw equirectangular plotting. Use a stable reference (module-level or memoised): a new object each render rebuilds the view and resets a roamed/zoomed map.
1440
+ - `aspectRatio`: number | string
1441
+ Container aspect ratio as `width / height` (e.g. `1.7` or `"16 / 9"`). The height derives from the rendered width so the map fills the frame with no letterboxing. Defaults to the projected aspect of the displayed window, so the regions fit edge-to-edge. Pass `height` to fix a pixel height instead.
1442
+ - `height`: number
1443
+ Fixed chart height in pixels. Overrides `aspectRatio` when set. Leave unset to size by aspect ratio (the default) so the map fills the container.
1444
+ - `className`: string
1445
+ - `isDarkMode`: boolean
1446
+
1447
+ **Examples:**
1448
+
1449
+ ```tsx
1450
+ <ChoroplethMap<CountryTraffic>
1451
+ echarts={echarts}
1452
+ geoJson={geoJson}
1453
+ data={countries}
1454
+ name="country"
1455
+ value="requests"
1456
+ valueFormat={fmt}
1457
+ isDarkMode={isDarkMode}
1458
+ />
1459
+ ```
1460
+
1461
+
908
1462
  ---
909
1463
 
910
1464
  ### ClipboardText
@@ -1460,8 +2014,8 @@ This is a compound component. Use these sub-components:
1460
2014
  Block sub-component
1461
2015
 
1462
2016
  Props:
1463
- - `code`: string (required)
1464
- - `lang`: CodeLang
2017
+ - `code`: string (required) - The code string to display.
2018
+ - `lang`: CodeLang - Language hint for the code content.
1465
2019
 
1466
2020
 
1467
2021
  ---
@@ -1496,37 +2050,37 @@ This is a compound component. Use these sub-components:
1496
2050
  Root sub-component
1497
2051
 
1498
2052
  Props:
1499
- - `className`: string
2053
+ - `className`: string - Additional CSS classes
1500
2054
 
1501
2055
  #### Collapsible.Trigger
1502
2056
 
1503
2057
  Trigger sub-component
1504
2058
 
1505
2059
  Props:
1506
- - `className`: string
2060
+ - `className`: string - Additional CSS classes
1507
2061
 
1508
2062
  #### Collapsible.Panel
1509
2063
 
1510
2064
  Panel sub-component
1511
2065
 
1512
2066
  Props:
1513
- - `className`: string
2067
+ - `className`: string - Additional CSS classes
1514
2068
 
1515
2069
  #### Collapsible.DefaultTrigger
1516
2070
 
1517
2071
  DefaultTrigger sub-component
1518
2072
 
1519
2073
  Props:
1520
- - `children`: ReactNode (required)
1521
- - `className`: string
2074
+ - `children`: ReactNode (required) - Label text displayed in the trigger
2075
+ - `className`: string - Additional CSS classes
1522
2076
 
1523
2077
  #### Collapsible.DefaultPanel
1524
2078
 
1525
2079
  DefaultPanel sub-component
1526
2080
 
1527
2081
  Props:
1528
- - `children`: ReactNode (required)
1529
- - `className`: string
2082
+ - `children`: ReactNode (required) - Panel content
2083
+ - `className`: string - Additional CSS classes
1530
2084
 
1531
2085
 
1532
2086
  **Examples:**
@@ -4954,37 +5508,37 @@ Info sub-component
4954
5508
 
4955
5509
  Props:
4956
5510
  - `children`: (props: {
4957
- - `page`: number (required)
4958
- - `perPage`: number
4959
- - `totalCount`: number
4960
- - `pageShowingRange`: string (required)
5511
+ page: number;
5512
+ perPage?: number;
5513
+ totalCount?: number;
5514
+ pageShowingRange: string;
5515
+ }) => ReactNode - Custom render function for the info text
5516
+ - `className`: string - Additional CSS classes
4961
5517
 
4962
5518
  #### Pagination.PageSize
4963
5519
 
4964
5520
  PageSize sub-component
4965
5521
 
4966
5522
  Props:
4967
- - `value`: number (required)
4968
- - `options`: number[]
4969
- - `page`: " (required)
4970
- - `label`: ReactNode
4971
- - `className`: string
5523
+ - `value`: number (required) - Current page size value
5524
+ - `options`: number[] - Available page size options
5525
+ - `label`: ReactNode - Label text shown before the selector.
5526
+ - `className`: string - Additional CSS classes
4972
5527
 
4973
5528
  #### Pagination.Controls
4974
5529
 
4975
5530
  Controls sub-component
4976
5531
 
4977
5532
  Props:
4978
- - `Note`: ** `"dropdown"` renders an option for every page (required)
4979
- - `pageSelector`: "input" | "dropdown"
4980
- - `className`: string
5533
+ - `pageSelector`: "input" | "dropdown" - How the page number selector is rendered in "full" controls mode. - `"input"` (default): A text input where users type a page number. - `"dropdown"`: A dropdown select with all page numbers as options. **Note:** `"dropdown"` renders an option for every page, so it is best suited for small page counts. For large datasets (hundreds of pages or more) prefer `"input"` to avoid rendering performance overhead.
5534
+ - `className`: string - Additional CSS classes
4981
5535
 
4982
5536
  #### Pagination.Separator
4983
5537
 
4984
5538
  Separator sub-component
4985
5539
 
4986
5540
  Props:
4987
- - `className`: string
5541
+ - `className`: string - Additional CSS classes
4988
5542
 
4989
5543
 
4990
5544
  **Examples:**
@@ -5401,19 +5955,28 @@ Radio — radio button group for single-select choices.
5401
5955
  - `variant`: enum [default: default]
5402
5956
  - `"default"`: Default radio appearance
5403
5957
  - `"error"`: Error state for validation failures
5404
- - `appearance`: enum [default: default]
5405
- - `"default"`: Standard inline radio item
5406
- - `"card"`: Choice card appearance with border, padding, and highlighted selection state
5407
-
5408
- **State Classes:**
5409
- - `"card"`:
5410
- - `hover`: `hover:bg-kumo-tint`
5411
- - `className`: string
5412
- Additional CSS classes
5413
- - `children`: ReactNode
5414
- Child elements
5958
+ - `appearance`: KumoRadioAppearance
5959
+ Visual appearance applied to all Radio.Item children. - `"default"` — Standard inline radio items - `"card"` — Choice card with border, padding, and highlighted selection state Individual items can override this with their own `appearance` prop.
5960
+ - `legend`: string
5961
+ Legend text for the group (required for accessibility). For more control over legend styling, omit this prop and use `<Radio.Legend>` as a child instead.
5962
+ - `children`: ReactNode (required)
5963
+ Child Radio.Item components (and optionally a Radio.Legend)
5964
+ - `orientation`: "vertical" | "horizontal"
5965
+ Layout direction of the radio items
5966
+ - `error`: string
5967
+ Error message for the group
5968
+ - `description`: ReactNode
5969
+ Helper text for the group
5415
5970
  - `value`: T
5416
5971
  The controlled value of the selected radio item.
5972
+ - `disabled`: boolean
5973
+ Whether all radios in the group are disabled
5974
+ - `controlPosition`: RadioControlPosition
5975
+ Position of radio control relative to label: "start" puts radio before label, "end" puts label before radio. Defaults to "start" for default appearance and "end" for card appearance.
5976
+ - `name`: string
5977
+ Form submission name for the radio group
5978
+ - `className`: string
5979
+ Additional CSS classes
5417
5980
  - `defaultValue`: T
5418
5981
  The uncontrolled initial value of the selected radio item.
5419
5982
  - `onValueChange`: (value: T, eventDetails: RadioGroupChangeEventDetails) => void
@@ -5436,7 +5999,17 @@ Item sub-component
5436
5999
  Group sub-component
5437
6000
 
5438
6001
  Props:
6002
+ - `legend`: string - Legend text for the group (required for accessibility). For more control over legend styling, omit this prop and use `<Radio.Legend>` as a child instead.
6003
+ - `children`: ReactNode (required) - Child Radio.Item components (and optionally a Radio.Legend)
6004
+ - `orientation`: "vertical" | "horizontal" - Layout direction of the radio items
6005
+ - `appearance`: KumoRadioAppearance - Visual appearance applied to all Radio.Item children. - `"default"` — Standard inline radio items - `"card"` — Choice card with border, padding, and highlighted selection state Individual items can override this with their own `appearance` prop.
6006
+ - `error`: string - Error message for the group
6007
+ - `description`: ReactNode - Helper text for the group
5439
6008
  - `value`: T - The controlled value of the selected radio item.
6009
+ - `disabled`: boolean - Whether all radios in the group are disabled
6010
+ - `controlPosition`: RadioControlPosition - Position of radio control relative to label: "start" puts radio before label, "end" puts label before radio. Defaults to "start" for default appearance and "end" for card appearance.
6011
+ - `name`: string - Form submission name for the radio group
6012
+ - `className`: string - Additional CSS classes
5440
6013
  - `defaultValue`: T - The uncontrolled initial value of the selected radio item.
5441
6014
  - `onValueChange`: (value: T, eventDetails: RadioGroupChangeEventDetails) => void - Callback fired when the selected value changes. The second argument carries native event details about the interaction.
5442
6015
 
@@ -5445,8 +6018,8 @@ Props:
5445
6018
  Legend sub-component
5446
6019
 
5447
6020
  Props:
5448
- - `children`: ReactNode (required)
5449
- - `className`: string
6021
+ - `children`: ReactNode (required) - Legend content
6022
+ - `className`: string - Additional CSS classes (e.g. "sr-only" to visually hide the legend)
5450
6023
 
5451
6024
 
5452
6025
  **Examples:**
@@ -5728,6 +6301,171 @@ Props:
5728
6301
  ```
5729
6302
 
5730
6303
 
6304
+ ---
6305
+
6306
+ ### SankeyChart
6307
+
6308
+ SankeyChart component
6309
+
6310
+ **Type:** component
6311
+
6312
+ **Import:** `import { SankeyChart } from "@cloudflare/kumo";`
6313
+
6314
+ **Category:** Data Visualization
6315
+
6316
+ **Props:**
6317
+
6318
+ - `echarts`: typeof echarts (required)
6319
+ The ECharts core instance imported by the consumer. Passed in rather than imported directly so the consumer controls which ECharts modules are bundled (tree-shaking).
6320
+ - `nodes`: SankeyNodeData[] (required)
6321
+ Array of nodes in the Sankey diagram
6322
+ - `links`: SankeyLinkData[] (required)
6323
+ Array of links connecting nodes by index
6324
+ - `height`: number
6325
+ Height of the chart in pixels
6326
+ - `showNodeValues`: boolean
6327
+ Show node values above labels (default: true if any node has a value)
6328
+ - `nodeLabelLayout`: "stacked" | "inline"
6329
+ Layout for node labels when showNodeValues is true. - 'stacked': value on top, name below (default) - 'inline': "value name" on a single line (better for small nodes)
6330
+ - `formatValue`: (value: number) => string
6331
+ Format function for node values (default: toLocaleString)
6332
+ - `tooltipFormatter`: (params: SankeyTooltipParams) => string
6333
+ Custom tooltip formatter. Return HTML string or empty string to hide tooltip.
6334
+ - `nodeWidth`: number
6335
+ - `nodePadding`: number
6336
+ - `showTooltip`: boolean
6337
+ - `defaultNodeColor`: string
6338
+ - `left`: number | string
6339
+ Left padding of the Sankey layout within the chart container. Accepts a number (px) or percentage string. ECharts default: '5%'.
6340
+ - `right`: number | string
6341
+ Right padding of the Sankey layout within the chart container. Accepts a number (px) or percentage string. ECharts default: '5%'.
6342
+ - `linkColor`: "gradient" | "gray"
6343
+ Link fill style: 'gradient' blends source to target colors, 'gray' uses flat gray
6344
+ - `linkOpacity`: number
6345
+ - `className`: string
6346
+ - `isDarkMode`: boolean
6347
+
6348
+ **Examples:**
6349
+
6350
+ ```tsx
6351
+ <SankeyChart
6352
+ echarts={echarts}
6353
+ nodes={basicNodes}
6354
+ links={basicLinks}
6355
+ height={350}
6356
+ isDarkMode={isDarkMode}
6357
+ />
6358
+ ```
6359
+
6360
+ ```tsx
6361
+ <SankeyChart
6362
+ echarts={echarts}
6363
+ nodes={previewNodes}
6364
+ links={previewLinks}
6365
+ height={200}
6366
+ showTooltip={false}
6367
+ isDarkMode={isDarkMode}
6368
+ />
6369
+ ```
6370
+
6371
+ ```tsx
6372
+ <SankeyChart
6373
+ echarts={echarts}
6374
+ nodes={multiLevelNodes}
6375
+ links={multiLevelLinks}
6376
+ height={350}
6377
+ nodeWidth={20}
6378
+ nodePadding={15}
6379
+ isDarkMode={isDarkMode}
6380
+ />
6381
+ ```
6382
+
6383
+ ```tsx
6384
+ <SankeyChart
6385
+ echarts={echarts}
6386
+ nodes={nodes}
6387
+ links={links}
6388
+ height={250}
6389
+ linkOpacity={0.6}
6390
+ isDarkMode={isDarkMode}
6391
+ />
6392
+ ```
6393
+
6394
+ ```tsx
6395
+ <SankeyChart
6396
+ echarts={echarts}
6397
+ nodes={nodes}
6398
+ links={links}
6399
+ height={300}
6400
+ tooltipFormatter={customTooltip}
6401
+ isDarkMode={isDarkMode}
6402
+ />
6403
+ ```
6404
+
6405
+ ```tsx
6406
+ <SankeyChart
6407
+ echarts={echarts}
6408
+ nodes={basicNodes}
6409
+ links={basicLinks}
6410
+ height={350}
6411
+ left={0}
6412
+ right={0}
6413
+ isDarkMode={isDarkMode}
6414
+ />
6415
+ ```
6416
+
6417
+ ```tsx
6418
+ <SankeyChart
6419
+ echarts={echarts}
6420
+ nodes={basicNodes}
6421
+ links={basicLinks}
6422
+ height={350}
6423
+ onNodeClick={handleNodeClick}
6424
+ onLinkClick={handleLinkClick}
6425
+ isDarkMode={isDarkMode}
6426
+ />
6427
+ ```
6428
+
6429
+ ```tsx
6430
+ <div className="flex w-full flex-col gap-2">
6431
+ <div className="flex items-center gap-2 text-sm text-kumo-subtle">
6432
+ <span>
6433
+ {hasSelection
6434
+ ? `Showing: ${[selectedSource, selectedTarget].filter(Boolean).join(" → ")}`
6435
+ : "Click a node to filter"}
6436
+ </span>
6437
+ {hasSelection && (
6438
+ <button
6439
+ onClick={resetFilters}
6440
+ className="text-kumo-brand hover:underline"
6441
+ >
6442
+ Reset
6443
+ </button>
6444
+ )}
6445
+ </div>
6446
+ <SankeyChart
6447
+ echarts={echarts}
6448
+ nodes={filteredNodes}
6449
+ links={filteredLinks}
6450
+ height={300}
6451
+ onNodeClick={handleNodeClick}
6452
+ isDarkMode={isDarkMode}
6453
+ />
6454
+ </div>
6455
+ ```
6456
+
6457
+ ```tsx
6458
+ <SankeyChart
6459
+ echarts={echarts}
6460
+ nodes={nodes}
6461
+ links={links}
6462
+ height={300}
6463
+ nodeLabelLayout="inline"
6464
+ isDarkMode={isDarkMode}
6465
+ />
6466
+ ```
6467
+
6468
+
5731
6469
  ---
5732
6470
 
5733
6471
  ### Select
@@ -6317,145 +7055,205 @@ This is a compound component. Use these sub-components:
6317
7055
  Provider sub-component
6318
7056
 
6319
7057
  Props:
6320
- - `defaultOpen`: boolean
6321
- - `open`: boolean
6322
- - `variant`: SidebarVariant
6323
- - `side`: SidebarSide
7058
+ - `defaultOpen`: boolean - Initial open state when uncontrolled.
7059
+ - `open`: boolean - Controlled open state.
7060
+ - `variant`: SidebarVariant - Sidebar layout variant.
7061
+ - `side`: SidebarSide - Which side the sidebar is on.
6324
7062
  - `collapsible`: "icon" | "offcanvas" | "none"
6325
- - `resizable`: boolean
6326
- - `defaultWidth`: number
6327
- - `minWidth`: number
6328
- - `maxWidth`: number
6329
- - `contained`: boolean
6330
- - `peekable`: boolean
6331
- - `animationDuration`: number
6332
- - `mobileBreakpoint`: number
6333
- - `children`: ReactNode (required)
6334
- - `className`: string
7063
+ - `resizable`: boolean - Enable drag-to-resize on the sidebar edge.
7064
+ - `defaultWidth`: number - Initial width in pixels when resizable.
7065
+ - `minWidth`: number - Minimum width in pixels when resizing.
7066
+ - `maxWidth`: number - Maximum width in pixels when resizing.
7067
+ - `contained`: boolean - When true, the collapsed sidebar uses absolute positioning instead of fixed, keeping it scoped inside a bounded parent. Useful for demos and embedded sidebars.
7068
+ - `peekable`: boolean - When true, hovering or focusing the collapsed sidebar temporarily expands it. The `state` will be `"peeking"` during the peek. Moving away collapses it back.
7069
+ - `animationDuration`: number - Duration of sidebar expand/collapse animation in milliseconds.
7070
+ - `mobileBreakpoint`: number - Viewport width (in px) below which the sidebar renders as a mobile dialog sheet instead of the desktop aside rail.
7071
+ - `children`: ReactNode (required) - Content — typically `<Sidebar>` + main content.
7072
+ - `className`: string - Additional CSS classes for the wrapper div.
6335
7073
 
6336
7074
  #### Sidebar.Header
6337
7075
 
6338
7076
  Header sub-component
6339
7077
 
6340
7078
  Props:
6341
- - `icon`: React.ComponentType<{ className?: string
7079
+ - `icon`: React.ComponentType<{ className?: string }> | React.ReactNode
7080
+ - `active`: boolean
7081
+ - `size`: SidebarMenuButtonSize - Button size. - `"base"` — Standard nav item - `"sm"` — Compact nav item
7082
+ - `href`: string
7083
+ - `target`: React.HTMLAttributeAnchorTarget - Link target — only meaningful when `href` is provided.
7084
+ - `tooltip`: string
7085
+ - `className`: string
7086
+ - `children`: ReactNode
6342
7087
 
6343
7088
  #### Sidebar.Content
6344
7089
 
6345
7090
  Content sub-component
6346
7091
 
6347
7092
  Props:
6348
- - `icon`: React.ComponentType<{ className?: string
7093
+ - `icon`: React.ComponentType<{ className?: string }> | React.ReactNode
7094
+ - `active`: boolean
7095
+ - `size`: SidebarMenuButtonSize - Button size. - `"base"` — Standard nav item - `"sm"` — Compact nav item
7096
+ - `href`: string
7097
+ - `target`: React.HTMLAttributeAnchorTarget - Link target — only meaningful when `href` is provided.
7098
+ - `tooltip`: string
7099
+ - `className`: string
7100
+ - `children`: ReactNode
6349
7101
 
6350
7102
  #### Sidebar.Footer
6351
7103
 
6352
7104
  Footer sub-component
6353
7105
 
6354
7106
  Props:
6355
- - `icon`: React.ComponentType<{ className?: string
7107
+ - `icon`: React.ComponentType<{ className?: string }> | React.ReactNode
7108
+ - `active`: boolean
7109
+ - `size`: SidebarMenuButtonSize - Button size. - `"base"` — Standard nav item - `"sm"` — Compact nav item
7110
+ - `href`: string
7111
+ - `target`: React.HTMLAttributeAnchorTarget - Link target — only meaningful when `href` is provided.
7112
+ - `tooltip`: string
7113
+ - `className`: string
7114
+ - `children`: ReactNode
6356
7115
 
6357
7116
  #### Sidebar.Group
6358
7117
 
6359
7118
  Group sub-component
6360
7119
 
6361
7120
  Props:
6362
- - `icon`: React.ComponentType<{ className?: string
7121
+ - `icon`: React.ComponentType<{ className?: string }> | React.ReactNode
7122
+ - `active`: boolean
7123
+ - `size`: SidebarMenuButtonSize - Button size. - `"base"` — Standard nav item - `"sm"` — Compact nav item
7124
+ - `href`: string
7125
+ - `target`: React.HTMLAttributeAnchorTarget - Link target — only meaningful when `href` is provided.
7126
+ - `tooltip`: string
7127
+ - `className`: string
7128
+ - `children`: ReactNode
6363
7129
 
6364
7130
  #### Sidebar.GroupLabel
6365
7131
 
6366
7132
  GroupLabel sub-component
6367
7133
 
6368
7134
  Props:
6369
- - `icon`: React.ComponentType<{ className?: string
7135
+ - `icon`: React.ComponentType<{ className?: string }> | React.ReactNode
7136
+ - `active`: boolean
7137
+ - `size`: SidebarMenuButtonSize - Button size. - `"base"` — Standard nav item - `"sm"` — Compact nav item
7138
+ - `href`: string
7139
+ - `target`: React.HTMLAttributeAnchorTarget - Link target — only meaningful when `href` is provided.
7140
+ - `tooltip`: string
7141
+ - `className`: string
7142
+ - `children`: ReactNode
6370
7143
 
6371
7144
  #### Sidebar.Menu
6372
7145
 
6373
7146
  Menu sub-component
6374
7147
 
6375
7148
  Props:
6376
- - `icon`: React.ComponentType<{ className?: string
7149
+ - `icon`: React.ComponentType<{ className?: string }> | React.ReactNode
7150
+ - `active`: boolean
7151
+ - `size`: SidebarMenuButtonSize - Button size. - `"base"` — Standard nav item - `"sm"` — Compact nav item
7152
+ - `href`: string
7153
+ - `target`: React.HTMLAttributeAnchorTarget - Link target — only meaningful when `href` is provided.
7154
+ - `tooltip`: string
7155
+ - `className`: string
7156
+ - `children`: ReactNode
6377
7157
 
6378
7158
  #### Sidebar.MenuItem
6379
7159
 
6380
7160
  MenuItem sub-component
6381
7161
 
6382
7162
  Props:
6383
- - `icon`: React.ComponentType<{ className?: string
7163
+ - `icon`: React.ComponentType<{ className?: string }> | React.ReactNode
7164
+ - `active`: boolean
7165
+ - `size`: SidebarMenuButtonSize - Button size. - `"base"` — Standard nav item - `"sm"` — Compact nav item
7166
+ - `href`: string
7167
+ - `target`: React.HTMLAttributeAnchorTarget - Link target — only meaningful when `href` is provided.
7168
+ - `tooltip`: string
7169
+ - `className`: string
7170
+ - `children`: ReactNode
6384
7171
 
6385
7172
  #### Sidebar.MenuButton
6386
7173
 
6387
7174
  MenuButton sub-component
6388
7175
 
6389
7176
  Props:
6390
- - `icon`: React.ComponentType<{ className?: string
7177
+ - `icon`: React.ComponentType<{ className?: string }> | React.ReactNode
7178
+ - `active`: boolean
7179
+ - `size`: SidebarMenuButtonSize - Button size. - `"base"` — Standard nav item - `"sm"` — Compact nav item
7180
+ - `href`: string
7181
+ - `target`: React.HTMLAttributeAnchorTarget - Link target — only meaningful when `href` is provided.
7182
+ - `tooltip`: string
7183
+ - `className`: string
7184
+ - `children`: ReactNode
6391
7185
 
6392
7186
  #### Sidebar.MenuBadge
6393
7187
 
6394
7188
  MenuBadge sub-component
6395
7189
 
6396
7190
  Props:
6397
- - `active`: boolean
6398
- - `href`: string
7191
+ - `active`: boolean - Marks this sub-item as currently active/selected.
7192
+ - `href`: string - Navigation URL. When set, renders as a link via LinkProvider.
7193
+ - `target`: React.HTMLAttributeAnchorTarget - Link target — only meaningful when `href` is provided.
6399
7194
 
6400
7195
  #### Sidebar.MenuSub
6401
7196
 
6402
7197
  MenuSub sub-component
6403
7198
 
6404
7199
  Props:
6405
- - `active`: boolean
6406
- - `href`: string
7200
+ - `active`: boolean - Marks this sub-item as currently active/selected.
7201
+ - `href`: string - Navigation URL. When set, renders as a link via LinkProvider.
7202
+ - `target`: React.HTMLAttributeAnchorTarget - Link target — only meaningful when `href` is provided.
6407
7203
 
6408
7204
  #### Sidebar.MenuSubItem
6409
7205
 
6410
7206
  MenuSubItem sub-component
6411
7207
 
6412
7208
  Props:
6413
- - `active`: boolean
6414
- - `href`: string
7209
+ - `active`: boolean - Marks this sub-item as currently active/selected.
7210
+ - `href`: string - Navigation URL. When set, renders as a link via LinkProvider.
7211
+ - `target`: React.HTMLAttributeAnchorTarget - Link target — only meaningful when `href` is provided.
6415
7212
 
6416
7213
  #### Sidebar.MenuSubButton
6417
7214
 
6418
7215
  MenuSubButton sub-component
6419
7216
 
6420
7217
  Props:
6421
- - `active`: boolean
6422
- - `href`: string
7218
+ - `active`: boolean - Marks this sub-item as currently active/selected.
7219
+ - `href`: string - Navigation URL. When set, renders as a link via LinkProvider.
7220
+ - `target`: React.HTMLAttributeAnchorTarget - Link target — only meaningful when `href` is provided.
6423
7221
 
6424
7222
  #### Sidebar.Separator
6425
7223
 
6426
7224
  Separator sub-component
6427
7225
 
6428
7226
  Props:
6429
- - `defaultOpen`: boolean
6430
- - `open`: boolean
6431
- - `autoScrollOnOpen`: boolean
7227
+ - `defaultOpen`: boolean - Initial open state (uncontrolled).
7228
+ - `open`: boolean - Controlled open state.
7229
+ - `autoScrollOnOpen`: boolean - Scroll the expanded content into view after opening.
6432
7230
 
6433
7231
  #### Sidebar.Trigger
6434
7232
 
6435
7233
  Trigger sub-component
6436
7234
 
6437
7235
  Props:
6438
- - `defaultOpen`: boolean
6439
- - `open`: boolean
6440
- - `autoScrollOnOpen`: boolean
7236
+ - `defaultOpen`: boolean - Initial open state (uncontrolled).
7237
+ - `open`: boolean - Controlled open state.
7238
+ - `autoScrollOnOpen`: boolean - Scroll the expanded content into view after opening.
6441
7239
 
6442
7240
  #### Sidebar.Rail
6443
7241
 
6444
7242
  Rail sub-component
6445
7243
 
6446
7244
  Props:
6447
- - `defaultOpen`: boolean
6448
- - `open`: boolean
6449
- - `autoScrollOnOpen`: boolean
7245
+ - `defaultOpen`: boolean - Initial open state (uncontrolled).
7246
+ - `open`: boolean - Controlled open state.
7247
+ - `autoScrollOnOpen`: boolean - Scroll the expanded content into view after opening.
6450
7248
 
6451
7249
  #### Sidebar.ResizeHandle
6452
7250
 
6453
7251
  ResizeHandle sub-component
6454
7252
 
6455
7253
  Props:
6456
- - `defaultOpen`: boolean
6457
- - `open`: boolean
6458
- - `autoScrollOnOpen`: boolean
7254
+ - `defaultOpen`: boolean - Initial open state (uncontrolled).
7255
+ - `open`: boolean - Controlled open state.
7256
+ - `autoScrollOnOpen`: boolean - Scroll the expanded content into view after opening.
6459
7257
 
6460
7258
  #### Sidebar.MenuChevron
6461
7259
 
@@ -6469,39 +7267,39 @@ Props:
6469
7267
  Collapsible sub-component
6470
7268
 
6471
7269
  Props:
6472
- - `defaultOpen`: boolean
6473
- - `open`: boolean
6474
- - `autoScrollOnOpen`: boolean
7270
+ - `defaultOpen`: boolean - Initial open state (uncontrolled).
7271
+ - `open`: boolean - Controlled open state.
7272
+ - `autoScrollOnOpen`: boolean - Scroll the expanded content into view after opening.
6475
7273
 
6476
7274
  #### Sidebar.CollapsibleTrigger
6477
7275
 
6478
7276
  CollapsibleTrigger sub-component
6479
7277
 
6480
7278
  Props:
6481
- - `render`: React.ReactElement (required)
7279
+ - `render`: React.ReactElement (required) - Element to render as the trigger. Gets aria-expanded, aria-controls, and onClick merged.
6482
7280
 
6483
7281
  #### Sidebar.CollapsibleContent
6484
7282
 
6485
7283
  CollapsibleContent sub-component
6486
7284
 
6487
7285
  Props:
6488
- - `activeKey`: string (required)
6489
- - `direction`: "left" | "right"
7286
+ - `activeKey`: string (required) - Key of the currently active view. Must match a child `SlidingView` value.
7287
+ - `direction`: "left" | "right" - Slide direction for the transition. - `"left"`: new view slides in from the right - `"right"`: new view slides in from the left
6490
7288
 
6491
7289
  #### Sidebar.SlidingViews
6492
7290
 
6493
7291
  SlidingViews sub-component
6494
7292
 
6495
7293
  Props:
6496
- - `activeKey`: string (required)
6497
- - `direction`: "left" | "right"
7294
+ - `activeKey`: string (required) - Key of the currently active view. Must match a child `SlidingView` value.
7295
+ - `direction`: "left" | "right" - Slide direction for the transition. - `"left"`: new view slides in from the right - `"right"`: new view slides in from the left
6498
7296
 
6499
7297
  #### Sidebar.SlidingView
6500
7298
 
6501
7299
  SlidingView sub-component
6502
7300
 
6503
7301
  Props:
6504
- - `value`: string (required)
7302
+ - `value`: string (required) - Unique key matching this view. Must correspond to `activeKey` on `SlidingViews`.
6505
7303
 
6506
7304
 
6507
7305
  **Examples:**
@@ -7146,21 +7944,21 @@ Item sub-component
7146
7944
  Group sub-component
7147
7945
 
7148
7946
  Props:
7149
- - `legend`: string
7150
- - `children`: ReactNode (required)
7151
- - `error`: string
7152
- - `description`: ReactNode
7153
- - `disabled`: boolean
7154
- - `controlFirst`: boolean
7155
- - `className`: string
7947
+ - `legend`: string - Legend text for the group. For more control over legend styling, omit this prop and use `<Switch.Legend>` as a child instead.
7948
+ - `children`: ReactNode (required) - Child Switch.Item components (and optionally a Switch.Legend)
7949
+ - `error`: string - Error message for the group (only appears in groups, not single switches)
7950
+ - `description`: ReactNode - Helper text for the group
7951
+ - `disabled`: boolean - Whether all switches in the group are disabled
7952
+ - `controlFirst`: boolean - When true (default), switch appears before label. When false, label appears before switch.
7953
+ - `className`: string - Additional CSS classes
7156
7954
 
7157
7955
  #### Switch.Legend
7158
7956
 
7159
7957
  Legend sub-component
7160
7958
 
7161
7959
  Props:
7162
- - `children`: ReactNode (required)
7163
- - `className`: string
7960
+ - `children`: ReactNode (required) - Legend content
7961
+ - `className`: string - Additional CSS classes (e.g. "sr-only" to visually hide the legend)
7164
7962
 
7165
7963
 
7166
7964
  **Examples:**
@@ -7770,16 +8568,17 @@ List sub-component
7770
8568
  Item sub-component
7771
8569
 
7772
8570
  Props:
7773
- - `active`: boolean
8571
+ - `active`: boolean - Whether this item represents the currently active section.
8572
+ - `render`: React.ReactElement - Custom element to render as the link. Use this to integrate with framework routers (e.g., Next.js `<Link>`, React Router `<NavLink>`). The element receives all anchor props including `href`, `className`, and `children`.
7774
8573
 
7775
8574
  #### TableOfContents.Group
7776
8575
 
7777
8576
  Group sub-component
7778
8577
 
7779
8578
  Props:
7780
- - `label`: string (required)
7781
- - `href`: string
7782
- - `active`: boolean
8579
+ - `label`: string (required) - Label displayed above the group's items.
8580
+ - `href`: string - URL the group label links to. When provided, the label renders as a clickable link with item styling.
8581
+ - `active`: boolean - Whether this group's label represents the currently active section. Only applies when `href` is provided.
7783
8582
 
7784
8583
 
7785
8584
  **Examples:**
@@ -8209,6 +9008,415 @@ Text component
8209
9008
  ```
8210
9009
 
8211
9010
 
9011
+ ---
9012
+
9013
+ ### TimeseriesChart
9014
+
9015
+ TimeseriesChart — a time-series line or bar chart.
9016
+
9017
+ **Type:** component
9018
+
9019
+ **Import:** `import { TimeseriesChart } from "@cloudflare/kumo";`
9020
+
9021
+ **Category:** Data Visualization
9022
+
9023
+ **Props:**
9024
+
9025
+ - `echarts`: typeof echarts (required)
9026
+ The ECharts core instance imported by the consumer. Passed in rather than imported directly so the consumer controls which ECharts modules are bundled (tree-shaking).
9027
+ - `type`: "line" | "bar"
9028
+ Visual style of each series. Defaults to `"line"`.
9029
+ - `data`: TimeseriesData[] (required)
9030
+ Array of time series data to display on the chart
9031
+ - `markers`: TimeseriesMarker[]
9032
+ Vertical reference markers rendered on the time axis.
9033
+ - `thresholds`: TimeseriesThreshold[]
9034
+ Horizontal threshold lines rendered on the value axis.
9035
+ - `xAxisName`: string
9036
+ Label for the x-axis (time axis)
9037
+ - `xAxisTickCount`: number
9038
+ Number of ticks to display on the x-axis
9039
+ - `xAxisTickFormat`: (value: number) => string
9040
+ Custom formatter for x-axis tick labels. Receives the raw timestamp in milliseconds and returns a display string, overriding ECharts' built-in time formatting.
9041
+ - `yAxisTickFormat`: (value: number) => string
9042
+ Custom formatter for y-axis tick labels. Receives the raw value and returns a display string. When omitted, ECharts' built-in formatter is used.
9043
+ - `yAxisTickLabelFormat`: (value: number) => string
9044
+ - `yAxisName`: string
9045
+ Label for the y-axis (value axis)
9046
+ - `yAxisTickCount`: number
9047
+ Number of ticks to display on the y-axis
9048
+ - `tooltipValueFormat`: (value: number) => string
9049
+ Custom formatter for tooltip values. Receives the raw y-value and returns a display string. When omitted, the raw value is shown. Takes precedence over the deprecated `yAxisTickLabelFormat` prop.
9050
+ - `tooltipMode`: "all" | "single"
9051
+ Controls which series are shown in the tooltip. - `"all"` — show all series at the hovered timestamp (default) - `"single"` — show only the series whose value is closest to the cursor
9052
+ - `tooltipMaxItems`: number
9053
+ Maximum number of series rows shown in the tooltip when `tooltipMode` is `"all"`. Additional series are hidden with a `+N more` footer. Defaults to `10`.
9054
+ - `tooltipBoundary`: "clipping-ancestors" | Element | Element[]
9055
+ Constrains the tooltip to stay within a specific element or region. By default the tooltip avoids overflowing any clipping ancestor (scroll containers, viewports, etc.). Pass an `Element` or array of elements to restrict the tooltip to a specific container.
9056
+ - `tooltipFollowCursor`: "both" | "x"
9057
+ Which axis the tooltip follows the cursor on. - `"both"` — tooltip tracks the cursor on both axes, staying near the pointer at all times. This is the default and matches the behaviour of ECharts' built-in tooltip. - `"x"` — tooltip follows the cursor horizontally but is locked to a fixed vertical position relative to the chart. This keeps the tooltip out of the way of the data and avoids vertical jitter as series values change — the same approach used by Recharts and many dashboard UIs. Only these two modes are offered because the x-axis is always time in a `TimeseriesChart`: y-only tracking and fully-fixed positioning don't produce useful tooltip behaviour for time-series data. Powered by Base UI Tooltip's `trackCursorAxis` under the hood.
9058
+ - `incomplete`: { before?: number; after?: number }
9059
+ Indicates incomplete data periods with optional before/after timestamps in ms
9060
+ - `enableLegendSelection`: boolean
9061
+ When `true`, adds a hidden ECharts legend so consumers can drive series visibility imperatively via the `legendSelect` / `legendUnSelect` / `legendToggleSelect` actions (e.g. to build a custom interactive legend). Toggled-off series are also excluded from the tooltip. Requires the consumer to register ECharts' `LegendComponent` (`echarts.use([LegendComponent])`); otherwise the legend actions no-op and, in development, ECharts logs a "component legend is used but not imported" warning.
9062
+ - `height`: number
9063
+ Height of the chart in pixels. Defaults to `350`.
9064
+ - `isDarkMode`: boolean
9065
+ When `true`, switches the chart to ECharts' built-in dark theme
9066
+ - `gradient`: boolean
9067
+ When `true`, renders a vertical gradient fill beneath each line series. The gradient fades from the series' color at the top to transparent at the bottom. Has no effect when `type` is `"bar"`.
9068
+ - `loading`: boolean
9069
+ When `true`, hides the chart and displays an animated sine-wave skeleton that oscillates back and forth to indicate that data is being fetched.
9070
+ - `ariaDescription`: string
9071
+ Accessible description for screen readers. When provided, it is passed to ECharts' `aria.label.description` and announced when the chart receives focus. Consumers are responsible for writing a meaningful description — see the W3C guidance on complex images for recommendations.
9072
+ - `optionUpdateBehavior`: SetOptionOpts
9073
+ Additional options passed as the second argument to `chart.setOption()`. Defaults to `{ notMerge: false, lazyUpdate: true }`.
9074
+
9075
+ **Colors (kumo tokens used):**
9076
+
9077
+ `bg-kumo-base`, `outline-kumo-fill`
9078
+
9079
+ **Examples:**
9080
+
9081
+ ```tsx
9082
+ <Chart
9083
+ echarts={echarts}
9084
+ options={options}
9085
+ height={400}
9086
+ isDarkMode={isDarkMode}
9087
+ />
9088
+ ```
9089
+
9090
+ ```tsx
9091
+ <TimeseriesChart
9092
+ echarts={echarts}
9093
+ isDarkMode={isDarkMode}
9094
+ data={data}
9095
+ xAxisName="Time (UTC)"
9096
+ yAxisName="Count"
9097
+ />
9098
+ ```
9099
+
9100
+ ```tsx
9101
+ <TimeseriesChart
9102
+ echarts={echarts}
9103
+ isDarkMode={isDarkMode}
9104
+ data={data}
9105
+ markers={markers}
9106
+ xAxisName="Time (UTC)"
9107
+ yAxisName="Count"
9108
+ />
9109
+ ```
9110
+
9111
+ ```tsx
9112
+ <TimeseriesChart
9113
+ echarts={echarts}
9114
+ isDarkMode={isDarkMode}
9115
+ data={data}
9116
+ thresholds={[
9117
+ {
9118
+ value: 55,
9119
+ label: "Memory limit",
9120
+ color: ChartPalette.semantic("Attention", isDarkMode),
9121
+ },
9122
+ ]}
9123
+ xAxisName="Time (UTC)"
9124
+ yAxisName="Memory (MB)"
9125
+ />
9126
+ ```
9127
+
9128
+ ```tsx
9129
+ <TimeseriesChart
9130
+ echarts={echarts}
9131
+ isDarkMode={isDarkMode}
9132
+ data={data}
9133
+ xAxisName="Time (UTC)"
9134
+ yAxisName="Requests"
9135
+ xAxisTickFormat={(ts) => {
9136
+ const d = new Date(ts);
9137
+ return `${d.getHours().toString().padStart(2, "0")}:${d.getMinutes().toString().padStart(2, "0")}`;
9138
+ }}
9139
+ yAxisTickFormat={(value) => {
9140
+ if (value >= 1000) return `${value / 1000}k`;
9141
+ return value.toString();
9142
+ }}
9143
+ tooltipValueFormat={(value) => `${(value / 1000).toFixed(1)}k requests`}
9144
+ />
9145
+ ```
9146
+
9147
+ ```tsx
9148
+ <TimeseriesChart
9149
+ yAxisTickCount={2}
9150
+ echarts={echarts}
9151
+ isDarkMode={isDarkMode}
9152
+ data={data}
9153
+ height={160}
9154
+ />
9155
+ ```
9156
+
9157
+ ```tsx
9158
+ <TimeseriesChart
9159
+ echarts={echarts}
9160
+ isDarkMode={isDarkMode}
9161
+ data={data}
9162
+ xAxisName="Time (UTC)"
9163
+ yAxisName="Mbps"
9164
+ incomplete={{ after: incompleteTimestamp }}
9165
+ />
9166
+ ```
9167
+
9168
+ ```tsx
9169
+ <TimeseriesChart
9170
+ echarts={echarts}
9171
+ isDarkMode={isDarkMode}
9172
+ data={data}
9173
+ xAxisName="Time (UTC)"
9174
+ yAxisName="%"
9175
+ onTimeRangeChange={(from, to) => {
9176
+ alert(
9177
+ `Selected range:\nFrom: ${new Date(from).toLocaleString()}\nTo: ${new Date(to).toLocaleString()}`,
9178
+ );
9179
+ }}
9180
+ />
9181
+ ```
9182
+
9183
+ ```tsx
9184
+ <div className="space-y-4">
9185
+ <h3 className="text-sm font-medium">Active State</h3>
9186
+
9187
+ <div className="flex flex-wrap gap-4 divide-x divide-kumo-hairline">
9188
+ <ChartLegend.LargeItem
9189
+ name="Requests"
9190
+ color={ChartPalette.semantic("Neutral", isDarkMode)}
9191
+ value="1,234"
9192
+ unit="req/s"
9193
+ />
9194
+ <ChartLegend.LargeItem
9195
+ name="Storage"
9196
+ color={ChartPalette.semantic("Attention", isDarkMode)}
9197
+ value="56"
9198
+ unit="GB"
9199
+ />
9200
+ <ChartLegend.LargeItem
9201
+ name="Warnings"
9202
+ color={ChartPalette.semantic("Warning", isDarkMode)}
9203
+ value="128"
9204
+ />
9205
+ </div>
9206
+
9207
+ <h3 className="text-sm font-medium mt-12">Inactive State</h3>
9208
+
9209
+ <div className="flex flex-wrap gap-4 divide-x divide-kumo-hairline">
9210
+ <ChartLegend.LargeItem
9211
+ name="Requests"
9212
+ color={ChartPalette.semantic("Neutral", isDarkMode)}
9213
+ value="1,234"
9214
+ unit="req/s"
9215
+ inactive
9216
+ />
9217
+ <ChartLegend.LargeItem
9218
+ name="Storage"
9219
+ color={ChartPalette.semantic("Attention", isDarkMode)}
9220
+ value="56"
9221
+ unit="GB"
9222
+ inactive
9223
+ />
9224
+ <ChartLegend.LargeItem
9225
+ name="Warnings"
9226
+ color={ChartPalette.semantic("Warning", isDarkMode)}
9227
+ value="128"
9228
+ inactive
9229
+ />
9230
+ </div>
9231
+ </div>
9232
+ ```
9233
+
9234
+ ```tsx
9235
+ <TimeseriesChart
9236
+ echarts={echarts}
9237
+ isDarkMode={isDarkMode}
9238
+ type="bar"
9239
+ data={data}
9240
+ xAxisName="Time (UTC)"
9241
+ yAxisName="Count"
9242
+ tooltipValueFormat={(r) => r.toFixed(2)}
9243
+ />
9244
+ ```
9245
+
9246
+ ```tsx
9247
+ <div className="flex flex-col flex-1 w-full">
9248
+ <TimeseriesChart
9249
+ echarts={echarts}
9250
+ isDarkMode={isDarkMode}
9251
+ xAxisName="Time (UTC)"
9252
+ yAxisName="Count"
9253
+ data={[]}
9254
+ loading
9255
+ />
9256
+ </div>
9257
+ ```
9258
+
9259
+ ```tsx
9260
+ <LayerCard>
9261
+ <LayerCard.Secondary>Read latency</LayerCard.Secondary>
9262
+ <LayerCard.Primary>
9263
+ <div className="flex divide-x divide-kumo-hairline gap-4 px-2 mb-2">
9264
+ <ChartLegend.LargeItem
9265
+ name="P99"
9266
+ color={ChartPalette.semantic("Attention", isDarkMode)}
9267
+ value="124"
9268
+ unit="ms"
9269
+ />
9270
+ <ChartLegend.LargeItem
9271
+ name="P95"
9272
+ color={ChartPalette.semantic("Warning", isDarkMode)}
9273
+ value="76"
9274
+ unit="ms"
9275
+ />
9276
+ <ChartLegend.LargeItem
9277
+ name="P75"
9278
+ color={ChartPalette.semantic("Neutral", isDarkMode)}
9279
+ value="32"
9280
+ unit="ms"
9281
+ />
9282
+ <ChartLegend.LargeItem
9283
+ name="P50"
9284
+ color={ChartPalette.semantic("Neutral", isDarkMode)}
9285
+ value="10"
9286
+ unit="ms"
9287
+ />
9288
+ </div>
9289
+ <TimeseriesChart
9290
+ xAxisName="Time (UTC)"
9291
+ echarts={echarts}
9292
+ isDarkMode={isDarkMode}
9293
+ data={data}
9294
+ height={300}
9295
+ />
9296
+ </LayerCard.Primary>
9297
+ </LayerCard>
9298
+ ```
9299
+
9300
+ ```tsx
9301
+ <LayerCard>
9302
+ <LayerCard.Secondary>Read latency</LayerCard.Secondary>
9303
+ <LayerCard.Primary>
9304
+ <div className="flex divide-x divide-kumo-line px-2 mb-2">
9305
+ {series.map((s) => (
9306
+ <ChartLegend.LargeItem
9307
+ key={s.name}
9308
+ name={s.name}
9309
+ color={s.color}
9310
+ value={s.value}
9311
+ unit={s.unit}
9312
+ inactive={hoveredSeries !== null && hoveredSeries !== s.name}
9313
+ onPointerEnter={() => {
9314
+ setHoveredSeries(s.name);
9315
+ chartRef.current?.dispatchAction({
9316
+ type: "highlight",
9317
+ seriesName: s.name,
9318
+ });
9319
+ }}
9320
+ onPointerLeave={() => {
9321
+ setHoveredSeries(null);
9322
+ chartRef.current?.dispatchAction({
9323
+ type: "downplay",
9324
+ seriesName: s.name,
9325
+ });
9326
+ }}
9327
+ className="not-first:pl-4"
9328
+ />
9329
+ ))}
9330
+ </div>
9331
+ <TimeseriesChart
9332
+ ref={chartRef}
9333
+ xAxisName="Time (UTC)"
9334
+ echarts={echarts}
9335
+ isDarkMode={isDarkMode}
9336
+ data={data}
9337
+ height={300}
9338
+ />
9339
+ </LayerCard.Primary>
9340
+ </LayerCard>
9341
+ ```
9342
+
9343
+ ```tsx
9344
+ <LayerCard>
9345
+ <LayerCard.Secondary>Read latency</LayerCard.Secondary>
9346
+ <LayerCard.Primary>
9347
+ <div className="flex divide-x divide-kumo-line px-2 mb-2">
9348
+ {series.map((s) => (
9349
+ <ChartLegend.LargeItem
9350
+ key={s.name}
9351
+ name={s.name}
9352
+ color={s.color}
9353
+ value={s.value}
9354
+ unit={s.unit}
9355
+ inactive={hiddenSeries[s.name] ?? false}
9356
+ onClick={() => handleClick(s.name)}
9357
+ className="not-first:pl-4"
9358
+ />
9359
+ ))}
9360
+ </div>
9361
+ <TimeseriesChart
9362
+ ref={chartRef}
9363
+ xAxisName="Time (UTC)"
9364
+ echarts={echarts}
9365
+ isDarkMode={isDarkMode}
9366
+ data={data}
9367
+ height={300}
9368
+ enableLegendSelection
9369
+ />
9370
+ </LayerCard.Primary>
9371
+ </LayerCard>
9372
+ ```
9373
+
9374
+ ```tsx
9375
+ <div className="flex w-full flex-col gap-4">
9376
+ <Select
9377
+ label="Tooltip follow cursor"
9378
+ value={selected}
9379
+ onValueChange={(v) => {
9380
+ if (v) setSelected(v);
9381
+ }}
9382
+ renderValue={(v) => v.label}
9383
+ >
9384
+ {FOLLOW_CURSOR_OPTIONS.map((opt) => (
9385
+ <Select.Option key={opt.value} value={opt}>
9386
+ {opt.label}
9387
+ </Select.Option>
9388
+ ))}
9389
+ </Select>
9390
+ <TimeseriesChart
9391
+ echarts={echarts}
9392
+ isDarkMode={isDarkMode}
9393
+ data={data}
9394
+ xAxisName="Time (UTC)"
9395
+ yAxisName="Latency (ms)"
9396
+ tooltipFollowCursor={selected.value}
9397
+ />
9398
+ </div>
9399
+ ```
9400
+
9401
+ ```tsx
9402
+ <div
9403
+ ref={boundaryRef}
9404
+ className="w-full overflow-auto rounded-lg border border-kumo-line"
9405
+ style={{ height: 300 }}
9406
+ >
9407
+ <TimeseriesChart
9408
+ echarts={echarts}
9409
+ isDarkMode={isDarkMode}
9410
+ data={data}
9411
+ xAxisName="Time (UTC)"
9412
+ yAxisName="Count"
9413
+ height={280}
9414
+ tooltipBoundary={boundary ?? undefined}
9415
+ />
9416
+ </div>
9417
+ ```
9418
+
9419
+
8212
9420
  ---
8213
9421
 
8214
9422
  ### Toasty
@@ -8229,10 +9437,12 @@ Toasty — toast notification provider and viewport.
8229
9437
  - `"error"`: Error toast for critical issues
8230
9438
  - `"warning"`: Warning toast for cautionary messages
8231
9439
  - `"info"`: Info toast for neutral informational messages
8232
- - `className`: string
8233
- Additional CSS classes
8234
- - `children`: ReactNode
8235
- Child elements
9440
+ - `children`: React.ReactNode (required)
9441
+ Application content. Toasts render via a portal above this.
9442
+ - `container`: PortalContainer
9443
+ Container element for the portal. Use this to render toasts inside a Shadow DOM or custom container. Overrides `KumoPortalProvider` context.
9444
+ - `toastManager`: ReturnType<typeof createKumoToastManager>
9445
+ Optional toast manager created by `createKumoToastManager()`. When provided, allows code outside the React tree (timers, module-load callbacks, query-cache listeners) to dispatch toasts via the same dedupe-aware manager that `useKumoToastManager()` returns inside the tree. Forwarded to the underlying `@base-ui/react/toast` `Toast.Provider` `toastManager` prop — see https://base-ui.com/react/components/toast for the upstream primitive.
8236
9446
 
8237
9447
  **Colors (kumo tokens used):**
8238
9448
 
@@ -8545,6 +9755,7 @@ Multi-line textarea input with Input variants and InputArea-specific dimensions
8545
9755
  - **Other:** Autocomplete, CloudflareLogo, DatePicker, Label, Link, SensitiveInput, Sidebar, Table, TableOfContents, Toolbar, DeleteResource
8546
9756
  - **Display:** Badge, Breadcrumbs, Code, Collapsible, Empty, LayerCard, Meter, Text
8547
9757
  - **Feedback:** Banner, Loader, Toasty
9758
+ - **Data Visualization:** BubbleMap, Chart, ChoroplethMap, SankeyChart, TimeseriesChart
8548
9759
  - **Action:** Button, ClipboardText
8549
9760
  - **Input:** Checkbox, Combobox, DateRangePicker, Field, Input, InputGroup, Radio, Select, Switch
8550
9761
  - **Navigation:** CommandPalette, MenuBar, Pagination, Tabs