@brightlocal/ui-components 2.15.0 → 2.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@brightlocal/ui-components",
3
- "version": "2.15.0",
3
+ "version": "2.16.0",
4
4
  "description": "BrightLocal Design System UI Components",
5
5
  "type": "module",
6
6
  "private": false,
@@ -42,6 +42,15 @@
42
42
  "import": "./dist/lib/utils.js",
43
43
  "require": "./dist/lib/utils.cjs"
44
44
  },
45
+ "./lib/use-dev-warning": {
46
+ "source": {
47
+ "types": "./src/lib/use-dev-warning.ts",
48
+ "import": "./src/lib/use-dev-warning.ts"
49
+ },
50
+ "types": "./dist/lib/use-dev-warning.d.ts",
51
+ "import": "./dist/lib/use-dev-warning.js",
52
+ "require": "./dist/lib/use-dev-warning.cjs"
53
+ },
45
54
  "./data-table": {
46
55
  "source": {
47
56
  "types": "./src/blocks/data-table.tsx",
@@ -130,8 +139,8 @@
130
139
  "vite-bundle-visualizer": "^1.2.1",
131
140
  "vite-plugin-dts": "^4.5.4",
132
141
  "vite-plugin-lib-inject-css": "^2.2.2",
133
- "@workspace/typescript-config": "0.0.0",
134
- "@workspace/eslint-config": "0.0.0"
142
+ "@workspace/eslint-config": "0.0.0",
143
+ "@workspace/typescript-config": "0.0.0"
135
144
  },
136
145
  "publishConfig": {
137
146
  "access": "public",
@@ -1,3 +1,5 @@
1
+ "use client";
2
+
1
3
  import * as React from "react";
2
4
  import { cva } from "class-variance-authority";
3
5
 
@@ -26,7 +28,14 @@ function subPadding(flush: boolean, density: CardDensity): string | false {
26
28
  }
27
29
 
28
30
  const cardVariants = cva(
29
- ["flex", "flex-col", "rounded-xl", "transition-colors", "w-full"],
31
+ [
32
+ "flex",
33
+ "flex-col",
34
+ "rounded-xl",
35
+ "transition-colors",
36
+ "w-full",
37
+ "max-w-[400px]",
38
+ ],
30
39
  {
31
40
  variants: {
32
41
  variant: {
@@ -84,8 +93,10 @@ type CardProps = React.ComponentProps<"div"> & {
84
93
  */
85
94
  trackingLabel?: string;
86
95
  /**
87
- * Maximum width of the card (e.g., "420px", "600px", "100%")
88
- * @default "400px"
96
+ * Maximum width of the card (e.g., "420px", "600px", "100%").
97
+ * Cards are full-width by default — use className="max-w-[400px]" instead.
98
+ * @default undefined
99
+ * @deprecated Use Tailwind max-width utilities via className instead (e.g., className="max-w-sm").
89
100
  */
90
101
  maxWidth?: string | number;
91
102
  };
@@ -103,7 +114,7 @@ const Card = React.forwardRef<HTMLDivElement, CardProps>(
103
114
  dataHook,
104
115
  trackingEl,
105
116
  trackingLabel,
106
- maxWidth = "400px",
117
+ maxWidth,
107
118
  children,
108
119
  style,
109
120
  ...props
@@ -112,6 +123,14 @@ const Card = React.forwardRef<HTMLDivElement, CardProps>(
112
123
  ) => {
113
124
  const flush = variant === "transparent-flush";
114
125
 
126
+ React.useEffect(() => {
127
+ if (process.env.NODE_ENV !== "production" && maxWidth !== undefined) {
128
+ console.warn(
129
+ 'Card: the "maxWidth" prop is deprecated. Use Tailwind max-width utilities via className instead (e.g., className="max-w-sm").'
130
+ );
131
+ }
132
+ }, [maxWidth]);
133
+
115
134
  const maxWidthStyle =
116
135
  maxWidth !== undefined
117
136
  ? {
@@ -177,14 +196,42 @@ const CardHeader = React.forwardRef<HTMLDivElement, CardSubComponentProps>(
177
196
  );
178
197
  CardHeader.displayName = "CardHeader";
179
198
 
199
+ /**
200
+ * Size variant for the CardTitle.
201
+ */
202
+ type CardTitleSize = "small" | "default";
203
+
204
+ const cardTitleVariants = cva("font-display font-medium", {
205
+ variants: {
206
+ size: {
207
+ small: "text-base",
208
+ default: "text-2xl",
209
+ },
210
+ },
211
+ defaultVariants: {
212
+ size: "default",
213
+ },
214
+ });
215
+
216
+ /**
217
+ * Props for the CardTitle component.
218
+ */
219
+ type CardTitleProps = CardSubComponentProps & {
220
+ /**
221
+ * Title text size.
222
+ * @default "default"
223
+ */
224
+ size?: CardTitleSize;
225
+ };
226
+
180
227
  /**
181
228
  * Title element within the Card header.
182
229
  */
183
- const CardTitle = React.forwardRef<HTMLDivElement, CardSubComponentProps>(
184
- ({ className, ...props }, ref) => (
230
+ const CardTitle = React.forwardRef<HTMLDivElement, CardTitleProps>(
231
+ ({ className, size = "default", ...props }, ref) => (
185
232
  <div
186
233
  ref={ref}
187
- className={cn("font-display text-2xl font-medium", className)}
234
+ className={cn(cardTitleVariants({ size }), className)}
188
235
  data-slot="card-title"
189
236
  {...props}
190
237
  />
@@ -301,4 +348,11 @@ export {
301
348
  CardContent,
302
349
  };
303
350
 
304
- export type { CardProps, CardSubComponentProps, CardVariant, CardDensity };
351
+ export type {
352
+ CardProps,
353
+ CardSubComponentProps,
354
+ CardTitleProps,
355
+ CardTitleSize,
356
+ CardVariant,
357
+ CardDensity,
358
+ };
@@ -572,7 +572,7 @@ function ComboboxValue<T>({
572
572
  return (
573
573
  <span
574
574
  className={cn(
575
- "text-foreground overflow-hidden text-base leading-normal font-medium text-ellipsis whitespace-nowrap",
575
+ "overflow-hidden text-base leading-normal font-medium text-ellipsis whitespace-nowrap",
576
576
  className
577
577
  )}
578
578
  data-slot="combobox-value"
@@ -92,7 +92,7 @@ const fieldVariants = cva(
92
92
  variant: {
93
93
  default: [],
94
94
  box: [
95
- "relative cursor-pointer",
95
+ "relative cursor-pointer gap-3",
96
96
  "rounded-lg border border-border bg-background p-3",
97
97
  "transition-colors",
98
98
  "[&_[data-slot=field-label]]:after:absolute [&_[data-slot=field-label]]:after:inset-0 [&_[data-slot=field-label]]:after:cursor-pointer",
@@ -101,9 +101,15 @@ const fieldVariants = cva(
101
101
  // Checked-state for radio/checkbox (not switch)
102
102
  "has-[[data-state=checked]:not([role=switch])]:border-primary has-[[data-state=checked]:not([role=switch])]:bg-primary/10",
103
103
  "dark:has-[[data-state=checked]:not([role=switch])]:bg-alpha-10",
104
+ // Disabled-state from child control
105
+ "has-[[data-disabled]]:cursor-not-allowed",
106
+ "[&:has([data-disabled])_[data-slot=field-label]]:after:cursor-not-allowed",
104
107
  // Error-state when inside an invalid container (e.g. RadioGroup with error)
105
108
  "[[aria-invalid=true]_&]:border-destructive-40",
106
109
  "[[aria-invalid=true]_&]:has-[:focus-visible]:border-destructive-40 [[aria-invalid=true]_&]:has-[:focus-visible]:shadow-destructive",
110
+ // Error-state from child control (standalone checkbox/radio)
111
+ "has-[[aria-invalid=true]]:border-destructive-40",
112
+ "has-[[aria-invalid=true]:focus-visible]:border-destructive-40 has-[[aria-invalid=true]:focus-visible]:shadow-destructive",
107
113
  ],
108
114
  },
109
115
  },
@@ -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
  >
@@ -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,