@brightlocal/ui-components 2.15.0 → 2.17.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 (44) hide show
  1. package/component-meta.json +10 -9
  2. package/deprecations.json +189 -0
  3. package/dist/badge.d.ts +1 -1
  4. package/dist/button.d.ts +1 -1
  5. package/dist/card.cjs +1 -1
  6. package/dist/card.d.ts +20 -4
  7. package/dist/card.d.ts.map +1 -1
  8. package/dist/card.js +95 -72
  9. package/dist/chart.cjs +4 -4
  10. package/dist/chart.d.ts +26 -0
  11. package/dist/chart.d.ts.map +1 -1
  12. package/dist/chart.js +75 -59
  13. package/dist/combobox.cjs +3 -3
  14. package/dist/combobox.js +33 -33
  15. package/dist/field.cjs +1 -1
  16. package/dist/field.d.ts.map +1 -1
  17. package/dist/field.js +10 -2
  18. package/dist/global-layout.cjs +1 -1
  19. package/dist/global-layout.d.ts +17 -2
  20. package/dist/global-layout.d.ts.map +1 -1
  21. package/dist/global-layout.js +53 -26
  22. package/dist/index.cjs +1 -1
  23. package/dist/index.js +366 -360
  24. package/dist/map.cjs +1 -1
  25. package/dist/map.d.ts +147 -4
  26. package/dist/map.d.ts.map +1 -1
  27. package/dist/map.js +375 -219
  28. package/dist/rating.cjs +1 -1
  29. package/dist/rating.d.ts +10 -0
  30. package/dist/rating.d.ts.map +1 -1
  31. package/dist/rating.js +38 -33
  32. package/dist/sheet.cjs +1 -1
  33. package/dist/sheet.d.ts +13 -2
  34. package/dist/sheet.d.ts.map +1 -1
  35. package/dist/sheet.js +38 -30
  36. package/package.json +18 -6
  37. package/src/components/card.tsx +62 -8
  38. package/src/components/chart.tsx +39 -1
  39. package/src/components/combobox.tsx +1 -1
  40. package/src/components/field.tsx +9 -1
  41. package/src/components/global-layout.tsx +60 -7
  42. package/src/components/map.tsx +414 -28
  43. package/src/components/rating.tsx +20 -1
  44. package/src/components/sheet.tsx +30 -5
@@ -71,6 +71,8 @@ const fieldVariants = cva(
71
71
  "[[data-slot=radio-group]_&]:relative [[data-slot=radio-group]_&]:cursor-pointer [[data-slot=radio-group]_&]:gap-3 [[data-slot=radio-group]_&]:has-[[data-disabled]]:cursor-not-allowed",
72
72
  // RadioGroup context: label overlay spans the full Field for clickable row
73
73
  "[[data-slot=radio-group]_&_[data-slot=field-label]]:after:absolute [[data-slot=radio-group]_&_[data-slot=field-label]]:after:inset-0 [[data-slot=radio-group]_&_[data-slot=field-label]]:after:cursor-pointer [[data-slot=radio-group]_&:has([data-disabled])_[data-slot=field-label]]:after:cursor-not-allowed",
74
+ // Checkbox context: match RadioGroup gap-3 spacing
75
+ "has-[>[role=checkbox]]:gap-3",
74
76
  // Label leading overrides: use leading-normal for wrap-capable labels (checkbox)
75
77
  "has-[>[role=checkbox]]:[&_[data-slot=field-label]]:leading-normal",
76
78
  ],
@@ -92,7 +94,7 @@ const fieldVariants = cva(
92
94
  variant: {
93
95
  default: [],
94
96
  box: [
95
- "relative cursor-pointer",
97
+ "relative cursor-pointer gap-3",
96
98
  "rounded-lg border border-border bg-background p-3",
97
99
  "transition-colors",
98
100
  "[&_[data-slot=field-label]]:after:absolute [&_[data-slot=field-label]]:after:inset-0 [&_[data-slot=field-label]]:after:cursor-pointer",
@@ -101,9 +103,15 @@ const fieldVariants = cva(
101
103
  // Checked-state for radio/checkbox (not switch)
102
104
  "has-[[data-state=checked]:not([role=switch])]:border-primary has-[[data-state=checked]:not([role=switch])]:bg-primary/10",
103
105
  "dark:has-[[data-state=checked]:not([role=switch])]:bg-alpha-10",
106
+ // Disabled-state from child control
107
+ "has-[[data-disabled]]:cursor-not-allowed",
108
+ "[&:has([data-disabled])_[data-slot=field-label]]:after:cursor-not-allowed",
104
109
  // Error-state when inside an invalid container (e.g. RadioGroup with error)
105
110
  "[[aria-invalid=true]_&]:border-destructive-40",
106
111
  "[[aria-invalid=true]_&]:has-[:focus-visible]:border-destructive-40 [[aria-invalid=true]_&]:has-[:focus-visible]:shadow-destructive",
112
+ // Error-state from child control (standalone checkbox/radio)
113
+ "has-[[aria-invalid=true]]:border-destructive-40",
114
+ "has-[[aria-invalid=true]:focus-visible]:border-destructive-40 has-[[aria-invalid=true]:focus-visible]:shadow-destructive",
107
115
  ],
108
116
  },
109
117
  },
@@ -42,7 +42,10 @@ const GlobalLayout = React.forwardRef<HTMLDivElement, GlobalLayoutProps>(
42
42
 
43
43
  return (
44
44
  <ScrollArea
45
- className={cn("h-dvh w-full", className)}
45
+ className={cn(
46
+ "h-dvh w-full [&>[data-radix-scroll-area-viewport]>div]:block! [&>[data-radix-scroll-area-viewport]>div]:min-w-0!",
47
+ className
48
+ )}
46
49
  dataHook={`${dataHook}-scroll`}
47
50
  scrollOrientation="both"
48
51
  >
@@ -143,7 +146,10 @@ const GlobalLayoutContent = React.forwardRef<
143
146
  return (
144
147
  <div
145
148
  ref={ref}
146
- className={cn("px-section-xs flex min-w-0 flex-1 flex-col", className)}
149
+ className={cn(
150
+ "px-section-xs flex min-w-0 flex-1 flex-col gap-6",
151
+ className
152
+ )}
147
153
  data-hook={dataHook}
148
154
  data-slot="content-wrapper"
149
155
  style={
@@ -185,7 +191,10 @@ const GlobalLayoutContentHeader = React.forwardRef<
185
191
  return (
186
192
  <Header
187
193
  ref={ref}
188
- className={cn("mx-auto w-full justify-between", className)}
194
+ className={cn(
195
+ "mx-auto w-full flex-wrap justify-between gap-4",
196
+ className
197
+ )}
189
198
  data-slot="content-header"
190
199
  dataHook={dataHook}
191
200
  style={{ maxWidth: "var(--ds-breakpoint-lg)" }}
@@ -201,6 +210,51 @@ const GlobalLayoutContentHeader = React.forwardRef<
201
210
 
202
211
  GlobalLayoutContentHeader.displayName = "GlobalLayoutContentHeader";
203
212
 
213
+ interface GlobalLayoutContentActionsProps extends React.ComponentProps<"div"> {
214
+ /**
215
+ * Data hook for automated testing (required)
216
+ */
217
+ dataHook: string;
218
+ /**
219
+ * Tracking element identifier for analytics
220
+ */
221
+ trackingEl?: string;
222
+ /**
223
+ * Tracking label for analytics context
224
+ */
225
+ trackingLabel?: string;
226
+ }
227
+
228
+ const GlobalLayoutContentActions = React.forwardRef<
229
+ HTMLDivElement,
230
+ GlobalLayoutContentActionsProps
231
+ >(
232
+ (
233
+ { className, dataHook, trackingEl, trackingLabel, children, ...props },
234
+ ref
235
+ ) => {
236
+ return (
237
+ <div
238
+ ref={ref}
239
+ className={cn(
240
+ "mx-auto hidden w-full items-center justify-end gap-2 lg:flex",
241
+ className
242
+ )}
243
+ data-hook={dataHook}
244
+ data-slot="content-actions"
245
+ data-tracking-el={trackingEl}
246
+ data-tracking-label={trackingLabel}
247
+ style={{ maxWidth: "var(--ds-breakpoint-lg)" }}
248
+ {...props}
249
+ >
250
+ {children}
251
+ </div>
252
+ );
253
+ }
254
+ );
255
+
256
+ GlobalLayoutContentActions.displayName = "GlobalLayoutContentActions";
257
+
204
258
  interface GlobalLayoutContentBodyProps extends React.ComponentProps<"div"> {
205
259
  /**
206
260
  * Data hook for automated testing
@@ -227,10 +281,7 @@ const GlobalLayoutContentBody = React.forwardRef<
227
281
  return (
228
282
  <div
229
283
  ref={ref}
230
- className={cn(
231
- "mx-auto mt-6 flex w-full flex-1 flex-col gap-6",
232
- className
233
- )}
284
+ className={cn("mx-auto flex w-full flex-1 flex-col gap-6", className)}
234
285
  data-hook={dataHook}
235
286
  data-slot="content-body"
236
287
  data-tracking-el={trackingEl}
@@ -309,6 +360,7 @@ export {
309
360
  GlobalLayout,
310
361
  GlobalLayoutSidebar,
311
362
  GlobalLayoutContent,
363
+ GlobalLayoutContentActions,
312
364
  GlobalLayoutContentHeader,
313
365
  GlobalLayoutContentBody,
314
366
  GlobalLayoutMobileHeader,
@@ -318,6 +370,7 @@ export type {
318
370
  GlobalLayoutProps,
319
371
  GlobalLayoutSidebarProps,
320
372
  GlobalLayoutContentProps,
373
+ GlobalLayoutContentActionsProps,
321
374
  GlobalLayoutContentHeaderProps,
322
375
  GlobalLayoutContentBodyProps,
323
376
  GlobalLayoutMobileHeaderProps,
@@ -138,25 +138,50 @@ const MAP_STYLES: Record<
138
138
  muted: { light: makeSatLightPreset(-40, 20), dark: DARK_PRESET },
139
139
  };
140
140
 
141
- function useIsDarkMode() {
142
- const [isDark, setIsDark] = React.useState(
143
- () =>
144
- typeof document !== "undefined" &&
145
- document.body.classList.contains("dark")
146
- );
141
+ // Shared dark mode store — one MutationObserver for all consumers
142
+ const _darkModeListeners = new Set<() => void>();
143
+ let _isDark =
144
+ typeof document !== "undefined" && document.body.classList.contains("dark");
145
+ let _darkModeObserverStarted = false;
146
+
147
+ function _initDarkModeObserver() {
148
+ if (_darkModeObserverStarted || typeof document === "undefined") return;
149
+ _darkModeObserverStarted = true;
150
+ const observer = new MutationObserver(() => {
151
+ const next = document.body.classList.contains("dark");
152
+ if (next !== _isDark) {
153
+ _isDark = next;
154
+ for (const fn of _darkModeListeners) fn();
155
+ }
156
+ });
157
+ observer.observe(document.body, {
158
+ attributes: true,
159
+ attributeFilter: ["class"],
160
+ });
161
+ }
147
162
 
148
- React.useEffect(() => {
149
- const observer = new MutationObserver(() => {
150
- setIsDark(document.body.classList.contains("dark"));
151
- });
152
- observer.observe(document.body, {
153
- attributes: true,
154
- attributeFilter: ["class"],
155
- });
156
- return () => observer.disconnect();
157
- }, []);
163
+ function _subscribeDarkMode(onStoreChange: () => void): () => void {
164
+ _darkModeListeners.add(onStoreChange);
165
+ _initDarkModeObserver();
166
+ return () => {
167
+ _darkModeListeners.delete(onStoreChange);
168
+ };
169
+ }
170
+
171
+ function _getDarkModeSnapshot(): boolean {
172
+ return _isDark;
173
+ }
158
174
 
159
- return isDark;
175
+ function _getDarkModeServerSnapshot(): boolean {
176
+ return false;
177
+ }
178
+
179
+ function useIsDarkMode(): boolean {
180
+ return React.useSyncExternalStore(
181
+ _subscribeDarkMode,
182
+ _getDarkModeSnapshot,
183
+ _getDarkModeServerSnapshot
184
+ );
160
185
  }
161
186
 
162
187
  /**
@@ -218,18 +243,49 @@ function resolveVariant(variant: MapGridPinVariant): ResolvedVariant {
218
243
  }
219
244
 
220
245
  /**
221
- * Background color classes for each ranking variant.
222
- * Shared by MapGridPin (CVA) and MapLegendItem so the pin and legend
223
- * colors stay in sync from a single source of truth.
246
+ * Single source of truth for ranking variant colors.
247
+ * Tailwind classes power MapGridPin / MapLegendItem; CSS vars + hex
248
+ * fallbacks power the cluster-pin SVG renderer.
224
249
  */
225
- const mapGridPinColorMap: Record<ResolvedVariant, string> = {
226
- strong: "bg-primary dark:bg-green-400",
227
- moderate: "bg-chart-4",
228
- weak: "bg-orange-400",
229
- unranked: "bg-red-600",
230
- error: "bg-warning-background dark:bg-orange-200",
250
+ const RANKING_COLORS: Record<
251
+ ResolvedVariant,
252
+ { className: string; cssVar: string; fallback: string }
253
+ > = {
254
+ strong: {
255
+ className: "bg-primary dark:bg-green-400",
256
+ cssVar: "--ds-tailwind-colors-green-400",
257
+ fallback: "#2ae855",
258
+ },
259
+ moderate: {
260
+ className: "bg-chart-4",
261
+ cssVar: "--ds-tailwind-colors-yellow-400",
262
+ fallback: "#facc15",
263
+ },
264
+ weak: {
265
+ className: "bg-orange-400",
266
+ cssVar: "--ds-tailwind-colors-orange-400",
267
+ fallback: "#fb923c",
268
+ },
269
+ unranked: {
270
+ className: "bg-red-600",
271
+ cssVar: "--ds-tailwind-colors-red-600",
272
+ fallback: "#dc2626",
273
+ },
274
+ error: {
275
+ className: "bg-warning-background dark:bg-orange-200",
276
+ cssVar: "--ds-tailwind-colors-orange-200",
277
+ fallback: "#fed7aa",
278
+ },
231
279
  };
232
280
 
281
+ /**
282
+ * Background color classes for each ranking variant.
283
+ * Derived from {@link RANKING_COLORS} — used by MapGridPin (CVA) and MapLegendItem.
284
+ */
285
+ const mapGridPinColorMap: Record<ResolvedVariant, string> = Object.fromEntries(
286
+ Object.entries(RANKING_COLORS).map(([k, v]) => [k, v.className])
287
+ ) as Record<ResolvedVariant, string>;
288
+
233
289
  const mapGridPinVariants = cva(
234
290
  "inline-flex items-center justify-center rounded-full font-sans text-sm font-semibold text-foreground dark:text-neutral-900 border-2 border-white shadow-sm transition-shadow duration-200 ease-out hover:shadow-md",
235
291
  {
@@ -331,6 +387,329 @@ const MapGridPin = React.forwardRef<HTMLDivElement, MapGridPinProps>(
331
387
 
332
388
  MapGridPin.displayName = "MapGridPin";
333
389
 
390
+ // ──────────────────────────────────────
391
+ // MapClusterPin
392
+ // ──────────────────────────────────────
393
+
394
+ interface ClusterPinResolvedStyles {
395
+ colors: Record<ResolvedVariant, string>;
396
+ fontFamily: string;
397
+ textColor: string;
398
+ }
399
+
400
+ function resolveClusterPinStyles(): ClusterPinResolvedStyles {
401
+ const fallbackColors = Object.fromEntries(
402
+ Object.entries(RANKING_COLORS).map(([k, v]) => [k, v.fallback])
403
+ ) as Record<ResolvedVariant, string>;
404
+ const fallback: ClusterPinResolvedStyles = {
405
+ colors: fallbackColors,
406
+ fontFamily: "Inter, system-ui, sans-serif",
407
+ textColor: "#111412",
408
+ };
409
+ if (typeof document === "undefined") return fallback;
410
+ const style = getComputedStyle(document.documentElement);
411
+ return {
412
+ colors: Object.fromEntries(
413
+ Object.entries(RANKING_COLORS).map(([k, { cssVar, fallback: fb }]) => [
414
+ k,
415
+ style.getPropertyValue(cssVar).trim() || fb,
416
+ ])
417
+ ) as Record<ResolvedVariant, string>,
418
+ fontFamily:
419
+ style.getPropertyValue("--ds-font-font-sans").trim() ||
420
+ fallback.fontFamily,
421
+ textColor:
422
+ style.getPropertyValue("--ds-tailwind-colors-neutral-950").trim() ||
423
+ fallback.textColor,
424
+ };
425
+ }
426
+
427
+ function resolveClusterPinColors(): Record<ResolvedVariant, string> {
428
+ return resolveClusterPinStyles().colors;
429
+ }
430
+
431
+ /**
432
+ * Resolved hex color values for each ranking variant.
433
+ * Reads from CSS custom properties at runtime so colors stay in sync
434
+ * with the design-token pipeline. Falls back to hardcoded hex for SSR.
435
+ *
436
+ * @deprecated Prefer calling {@link resolveClusterPinColors} directly
437
+ * for guaranteed up-to-date values. This static snapshot is kept for
438
+ * backward compatibility.
439
+ */
440
+ const clusterPinHexColors: Record<ResolvedVariant, string> = Object.fromEntries(
441
+ Object.entries(RANKING_COLORS).map(([k, v]) => [k, v.fallback])
442
+ ) as Record<ResolvedVariant, string>;
443
+
444
+ /** A single segment in a cluster pin pie chart. */
445
+ interface ClusterPinSegment {
446
+ /** Ranking variant that determines this segment's color */
447
+ variant: ResolvedVariant;
448
+ /** Number of pins with this variant */
449
+ count: number;
450
+ }
451
+
452
+ /** Consistent ordering: best → worst ranking. */
453
+ const VARIANT_ORDER: ResolvedVariant[] = [
454
+ "strong",
455
+ "moderate",
456
+ "weak",
457
+ "unranked",
458
+ "error",
459
+ ];
460
+
461
+ /**
462
+ * Generates an SVG string for a cluster pie-chart pin.
463
+ *
464
+ * The SVG is a circle divided into colored sectors proportional to each
465
+ * segment's count, with a white inner circle displaying the total count.
466
+ * Colors are resolved from design-token CSS custom properties at runtime
467
+ * via {@link resolveClusterPinColors} and match the {@link MapGridPin}
468
+ * ranking palette.
469
+ *
470
+ * @param segments - Ranking variant distribution for the cluster
471
+ * @param total - Total count displayed in the center
472
+ *
473
+ * @example
474
+ * ```tsx
475
+ * // Generate SVG for a cluster with mixed rankings
476
+ * const svg = createClusterPinSvg(
477
+ * [
478
+ * { variant: "strong", count: 5 },
479
+ * { variant: "moderate", count: 3 },
480
+ * { variant: "weak", count: 1 },
481
+ * ],
482
+ * 9
483
+ * );
484
+ * ```
485
+ *
486
+ * @example
487
+ * ```tsx
488
+ * // Wire up with @googlemaps/markerclusterer
489
+ * import { createClusterPinElement } from "@brightlocal/ui-components/map";
490
+ *
491
+ * new MarkerClusterer({
492
+ * map,
493
+ * markers,
494
+ * renderer: {
495
+ * render(cluster) {
496
+ * const el = createClusterPinElement({
497
+ * markers: cluster.markers,
498
+ * count: cluster.count,
499
+ * getVariant: (m) => dataMap.get(m)?.variant ?? "unranked",
500
+ * });
501
+ * return new google.maps.marker.AdvancedMarkerElement({
502
+ * position: cluster.position,
503
+ * content: el,
504
+ * zIndex: 1000 + cluster.count,
505
+ * });
506
+ * },
507
+ * },
508
+ * });
509
+ * ```
510
+ */
511
+ function createClusterPinSvg(
512
+ segments: ClusterPinSegment[],
513
+ total: number
514
+ ): string {
515
+ const { colors, fontFamily, textColor } = resolveClusterPinStyles();
516
+ const size = 40;
517
+ const half = size / 2;
518
+ const border = 2;
519
+ const outerR = half - border;
520
+ const innerR = outerR * 0.55;
521
+
522
+ const sorted = [...segments].sort(
523
+ (a, b) =>
524
+ VARIANT_ORDER.indexOf(a.variant) - VARIANT_ORDER.indexOf(b.variant)
525
+ );
526
+ const nonEmpty = sorted.filter((s) => s.count > 0);
527
+ const segmentTotal = nonEmpty.reduce((sum, s) => sum + s.count, 0) || 1;
528
+ const displayTotal = Math.max(Number(total) || 0, 1);
529
+
530
+ let sectors: string;
531
+
532
+ const only = nonEmpty[0];
533
+ if (nonEmpty.length <= 1) {
534
+ const fill = only ? colors[only.variant] : "#e5e7eb";
535
+ sectors = `<circle cx="${half}" cy="${half}" r="${outerR}" fill="${fill}"/>`;
536
+ } else {
537
+ sectors = "";
538
+ let angle = -Math.PI / 2;
539
+ for (const seg of nonEmpty) {
540
+ const sweep = (seg.count / segmentTotal) * Math.PI * 2;
541
+ const end = angle + sweep;
542
+ const x1 = half + outerR * Math.cos(angle);
543
+ const y1 = half + outerR * Math.sin(angle);
544
+ const x2 = half + outerR * Math.cos(end);
545
+ const y2 = half + outerR * Math.sin(end);
546
+ const large = sweep > Math.PI ? 1 : 0;
547
+ sectors += `<path d="M${half},${half}L${x1.toFixed(2)},${y1.toFixed(2)}A${outerR},${outerR} 0 ${large} 1 ${x2.toFixed(2)},${y2.toFixed(2)}Z" fill="${colors[seg.variant]}"/>`;
548
+ angle = end;
549
+ }
550
+ }
551
+
552
+ const fontSize = Math.round(size * 0.3);
553
+
554
+ return [
555
+ `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 ${size} ${size}" style="filter:drop-shadow(0 1px 2px rgba(0,0,0,.15))">`,
556
+ `<circle cx="${half}" cy="${half}" r="${half}" fill="white"/>`,
557
+ sectors,
558
+ `<circle cx="${half}" cy="${half}" r="${outerR}" fill="none" stroke="white" stroke-width="${border}"/>`,
559
+ `<circle cx="${half}" cy="${half}" r="${innerR}" fill="white"/>`,
560
+ `<text x="${half}" y="${half}" text-anchor="middle" dominant-baseline="central" font-family="${fontFamily}" font-size="${fontSize}" font-weight="600" fill="${textColor}">${displayTotal}</text>`,
561
+ `</svg>`,
562
+ ].join("");
563
+ }
564
+
565
+ /**
566
+ * Options for {@link createClusterPinElement}.
567
+ */
568
+ interface CreateClusterPinElementOptions {
569
+ /** Markers grouped in this cluster. Each is passed to `getVariant`. */
570
+ markers: unknown[];
571
+ /** Total marker count for the cluster label. */
572
+ count: number;
573
+ /**
574
+ * Extracts the ranking variant from a single marker.
575
+ * Called once per marker; unknown markers should return `"unranked"`.
576
+ */
577
+ getVariant: (marker: unknown) => ResolvedVariant;
578
+ }
579
+
580
+ /**
581
+ * Creates an SVG DOM element for a cluster pin, ready to be used as
582
+ * `content` for a Google Maps `AdvancedMarkerElement`.
583
+ *
584
+ * Tallies the ranking variants across all markers in the cluster,
585
+ * generates a pie-chart SVG via {@link createClusterPinSvg}, and
586
+ * returns the parsed `SVGElement`.
587
+ *
588
+ * @example
589
+ * ```tsx
590
+ * import { createClusterPinElement } from "@brightlocal/ui-components/map";
591
+ * import { MarkerClusterer } from "@googlemaps/markerclusterer";
592
+ *
593
+ * // Store per-marker data in a WeakMap
594
+ * const pinData = new WeakMap<google.maps.marker.AdvancedMarkerElement, { variant: "strong" | "moderate" | "weak" | "unranked" }>();
595
+ *
596
+ * new MarkerClusterer({
597
+ * map,
598
+ * markers,
599
+ * renderer: {
600
+ * render(cluster) {
601
+ * const el = createClusterPinElement({
602
+ * markers: cluster.markers,
603
+ * count: cluster.count,
604
+ * getVariant: (m) => pinData.get(m)?.variant ?? "unranked",
605
+ * });
606
+ * return new google.maps.marker.AdvancedMarkerElement({
607
+ * position: cluster.position,
608
+ * content: el,
609
+ * zIndex: 1000 + cluster.count,
610
+ * });
611
+ * },
612
+ * },
613
+ * });
614
+ * ```
615
+ */
616
+ function createClusterPinElement(
617
+ options: CreateClusterPinElementOptions
618
+ ): SVGElement {
619
+ if (typeof DOMParser === "undefined") {
620
+ throw new Error(
621
+ "createClusterPinElement requires a browser environment (DOMParser). Use createClusterPinSvg for SSR."
622
+ );
623
+ }
624
+
625
+ const { markers, count, getVariant } = options;
626
+
627
+ const tally = new Map<ResolvedVariant, number>();
628
+ for (const marker of markers) {
629
+ const v = getVariant(marker);
630
+ tally.set(v, (tally.get(v) ?? 0) + 1);
631
+ }
632
+
633
+ const segments: ClusterPinSegment[] = [];
634
+ for (const v of VARIANT_ORDER) {
635
+ const c = tally.get(v);
636
+ if (c) segments.push({ variant: v, count: c });
637
+ }
638
+
639
+ const svgStr = createClusterPinSvg(segments, count);
640
+ const parser = new DOMParser();
641
+ const doc = parser.parseFromString(svgStr, "image/svg+xml");
642
+ const svg = doc.documentElement;
643
+ if (!(svg instanceof SVGElement)) {
644
+ throw new Error("createClusterPinElement: failed to parse SVG");
645
+ }
646
+ return svg;
647
+ }
648
+
649
+ /**
650
+ * Props for the MapClusterPin component.
651
+ */
652
+ interface MapClusterPinProps extends Omit<
653
+ React.ComponentProps<"div">,
654
+ "children"
655
+ > {
656
+ /** Distribution of ranking variants to display as pie sectors */
657
+ segments: ClusterPinSegment[];
658
+ /** Total count displayed in the center */
659
+ count: number;
660
+ /** Required test hook identifier */
661
+ dataHook: string;
662
+ /** Analytics element identifier */
663
+ trackingEl?: string;
664
+ /** Analytics label */
665
+ trackingLabel?: string;
666
+ }
667
+
668
+ /**
669
+ * A cluster pin that visualises the ranking distribution of grouped map pins
670
+ * as a pie chart. Each colored sector is proportional to the number of pins
671
+ * with that ranking variant; the total count is displayed in the center.
672
+ *
673
+ * Use as a standalone React component in stories or documentation.
674
+ * For Google Maps integration, use {@link createClusterPinElement} instead.
675
+ */
676
+ const MapClusterPin = React.forwardRef<HTMLDivElement, MapClusterPinProps>(
677
+ (
678
+ {
679
+ segments,
680
+ count,
681
+ dataHook,
682
+ className,
683
+ trackingEl,
684
+ trackingLabel,
685
+ ...props
686
+ },
687
+ ref
688
+ ) => {
689
+ const segmentsKey = JSON.stringify(segments);
690
+ const svg = React.useMemo(
691
+ () => createClusterPinSvg(segments, count),
692
+ // eslint-disable-next-line react-hooks/exhaustive-deps -- serialised key for stable comparison
693
+ [segmentsKey, count]
694
+ );
695
+
696
+ return (
697
+ <div
698
+ dangerouslySetInnerHTML={{ __html: svg }}
699
+ ref={ref}
700
+ className={cn("inline-flex items-center justify-center", className)}
701
+ data-hook={dataHook}
702
+ data-slot="map-cluster-pin"
703
+ data-tracking-el={trackingEl || "map-cluster-pin"}
704
+ data-tracking-label={trackingLabel}
705
+ {...props}
706
+ />
707
+ );
708
+ }
709
+ );
710
+
711
+ MapClusterPin.displayName = "MapClusterPin";
712
+
334
713
  // ──────────────────────────────────────
335
714
  // MapLocationPin
336
715
  // ──────────────────────────────────────
@@ -847,13 +1226,12 @@ const MapLegend = React.forwardRef<HTMLDivElement, MapLegendProps>(
847
1226
  ref={ref}
848
1227
  aria-label={ariaLabel ?? "Map legend"}
849
1228
  className={cn(
850
- "inline-flex w-auto flex-row items-center bg-white font-sans dark:bg-neutral-800",
1229
+ "inline-flex w-auto max-w-none flex-row items-center bg-white font-sans dark:bg-neutral-800",
851
1230
  className
852
1231
  )}
853
1232
  data-slot="map-legend"
854
1233
  dataHook={dataHook}
855
1234
  density="condensed"
856
- maxWidth="none"
857
1235
  role="group"
858
1236
  trackingEl={trackingEl || "map-legend"}
859
1237
  trackingLabel={trackingLabel}
@@ -1109,7 +1487,12 @@ export {
1109
1487
  MapTypeId,
1110
1488
  MapLocationPin,
1111
1489
  MapGridPin,
1490
+ MapClusterPin,
1112
1491
  mapGridPinColorMap,
1492
+ clusterPinHexColors,
1493
+ resolveClusterPinColors,
1494
+ createClusterPinSvg,
1495
+ createClusterPinElement,
1113
1496
  MapControlButton,
1114
1497
  MapLoadingState,
1115
1498
  MapErrorState,
@@ -1130,6 +1513,9 @@ export type {
1130
1513
  MapLocationPinProps,
1131
1514
  MapGridPinProps,
1132
1515
  MapGridPinVariant,
1516
+ MapClusterPinProps,
1517
+ ClusterPinSegment,
1518
+ CreateClusterPinElementOptions,
1133
1519
  MapControlButtonProps,
1134
1520
  MapLoadingStateProps,
1135
1521
  MapErrorStateProps,