@brightlocal/ui-components 2.13.0 → 2.15.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.
@@ -1,5 +1,12 @@
1
+ "use client";
2
+
1
3
  import * as React from "react";
2
- import { AlertCircle } from "@brightlocal/icons";
4
+ import { cva } from "class-variance-authority";
5
+ import { RefreshCw, Store, TriangleAlert } from "@brightlocal/icons";
6
+ import {
7
+ GlobeyFixingFault,
8
+ MapBackground as MapBackgroundImage,
9
+ } from "@brightlocal/illustrations";
3
10
  import { Button } from "@brightlocal/ui-components/button";
4
11
  import { Card, CardContent } from "@brightlocal/ui-components/card";
5
12
  import { cn } from "@brightlocal/ui-components/lib/utils";
@@ -24,7 +31,7 @@ import {
24
31
  const MapTypeId = {
25
32
  /** Default road map view */
26
33
  ROADMAP: "roadmap",
27
- /** Satellite imagery */
34
+ /** @deprecated Satellite imagery — prefer cloud-based map styling via Map ID */
28
35
  SATELLITE: "satellite",
29
36
  } as const;
30
37
 
@@ -33,37 +40,230 @@ const MapTypeId = {
33
40
  */
34
41
  type MapTypeIdValue = (typeof MapTypeId)[keyof typeof MapTypeId];
35
42
 
43
+ // ──────────────────────────────────────
44
+ // MapStyleVariant & useMapStyles
45
+ // ──────────────────────────────────────
46
+
47
+ /**
48
+ * Visual variant for map styling.
49
+ * - `"default"` — Standard Google Maps appearance (no custom styles in light mode)
50
+ * - `"muted"` — Desaturated, softened map appearance so UI elements stand out
51
+ */
52
+ type MapStyleVariant = "default" | "muted";
53
+
54
+ /**
55
+ * A single Google Maps JSON style rule.
56
+ * Matches the `google.maps.MapTypeStyle` shape so values can be passed
57
+ * directly to the `styles` prop of `@vis.gl/react-google-maps` `<Map>`.
58
+ */
59
+ type MapStyleRule = {
60
+ featureType?: string;
61
+ elementType?: string;
62
+ stylers: Record<string, string | number>[];
63
+ };
64
+
65
+ const FEATURE_TYPES = ["water", "landscape", "road", "poi", "transit"] as const;
66
+
67
+ function makeSatLightPreset(
68
+ saturation: number,
69
+ lightness: number
70
+ ): MapStyleRule[] {
71
+ return [
72
+ ...FEATURE_TYPES.map((ft) => ({
73
+ featureType: ft,
74
+ elementType: "geometry",
75
+ stylers: [{ saturation, lightness }],
76
+ })),
77
+ {
78
+ elementType: "labels.text.fill",
79
+ stylers: [{ saturation, lightness: lightness - 10 }],
80
+ },
81
+ {
82
+ elementType: "labels.icon",
83
+ stylers: [{ saturation, lightness }],
84
+ },
85
+ ];
86
+ }
87
+
88
+ const DARK_PRESET: MapStyleRule[] = [
89
+ { elementType: "geometry", stylers: [{ color: "#444444" }] },
90
+ { elementType: "labels.text.fill", stylers: [{ color: "#aaaaaa" }] },
91
+ { elementType: "labels.text.stroke", stylers: [{ color: "#323232" }] },
92
+ {
93
+ featureType: "water",
94
+ elementType: "geometry",
95
+ stylers: [{ color: "#30405a" }],
96
+ },
97
+ {
98
+ featureType: "landscape",
99
+ elementType: "geometry",
100
+ stylers: [{ color: "#4b4b4b" }],
101
+ },
102
+ {
103
+ featureType: "road",
104
+ elementType: "geometry",
105
+ stylers: [{ color: "#5c5c5c" }],
106
+ },
107
+ {
108
+ featureType: "road",
109
+ elementType: "geometry.stroke",
110
+ stylers: [{ color: "#3e3e3e" }],
111
+ },
112
+ {
113
+ featureType: "poi",
114
+ elementType: "geometry",
115
+ stylers: [{ color: "#525252" }],
116
+ },
117
+ {
118
+ featureType: "transit",
119
+ elementType: "geometry",
120
+ stylers: [{ color: "#505050" }],
121
+ },
122
+ { elementType: "labels.icon", stylers: [{ visibility: "off" }] },
123
+ ];
124
+
125
+ /**
126
+ * Built-in map style presets keyed by `variant.theme`.
127
+ *
128
+ * - `default.light` — empty (uses native Google Maps styling)
129
+ * - `default.dark` — dark colour palette based on "Example 3 Dark"
130
+ * - `muted.light` — desaturated/lightened based on "Example 2" (`sat -40, light +20`)
131
+ * - `muted.dark` — same dark palette as `default.dark`
132
+ */
133
+ const MAP_STYLES: Record<
134
+ MapStyleVariant,
135
+ { light: MapStyleRule[]; dark: MapStyleRule[] }
136
+ > = {
137
+ default: { light: [], dark: DARK_PRESET },
138
+ muted: { light: makeSatLightPreset(-40, 20), dark: DARK_PRESET },
139
+ };
140
+
141
+ function useIsDarkMode() {
142
+ const [isDark, setIsDark] = React.useState(
143
+ () =>
144
+ typeof document !== "undefined" &&
145
+ document.body.classList.contains("dark")
146
+ );
147
+
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
+ }, []);
158
+
159
+ return isDark;
160
+ }
161
+
162
+ /**
163
+ * Returns the appropriate `google.maps.MapTypeStyle[]` for the given variant
164
+ * and the current color scheme (light/dark). Pass the returned array to the
165
+ * `styles` prop of `@vis.gl/react-google-maps` `<Map>`.
166
+ *
167
+ * Dark mode is detected automatically via the `dark` class on `document.body`.
168
+ *
169
+ * > **Note:** JSON styling works with **raster maps only** (no `mapId` prop).
170
+ * > For vector maps use [Cloud-based Map Styling](https://developers.google.com/maps/documentation/javascript/cloud-based-map-styling).
171
+ *
172
+ * @example
173
+ * ```tsx
174
+ * import { useMapStyles } from "@brightlocal/ui-components/map";
175
+ *
176
+ * function MyMap() {
177
+ * const styles = useMapStyles("muted");
178
+ * return <Map styles={styles} defaultCenter={center} defaultZoom={14} />;
179
+ * }
180
+ * ```
181
+ */
182
+ function useMapStyles(variant: MapStyleVariant = "default"): MapStyleRule[] {
183
+ const isDark = useIsDarkMode();
184
+ return MAP_STYLES[variant][isDark ? "dark" : "light"];
185
+ }
186
+
36
187
  // ──────────────────────────────────────
37
188
  // MapGridPin
38
189
  // ──────────────────────────────────────
39
190
 
40
- type MapGridPinVariant =
191
+ type ResolvedVariant = "strong" | "moderate" | "weak" | "unranked" | "error";
192
+
193
+ /** @deprecated Legacy variant names kept for backward compatibility. */
194
+ type LegacyVariant =
41
195
  | "primary"
42
196
  | "secondary"
43
197
  | "destructive"
44
198
  | "outline"
45
199
  | "warning";
46
200
 
47
- const gridPinPulseVar: Record<MapGridPinVariant, string> = {
48
- primary: "var(--primary)",
49
- secondary: "var(--secondary)",
50
- destructive: "var(--destructive)",
51
- outline: "var(--muted)",
52
- warning: "var(--warning-background)",
201
+ type MapGridPinVariant = ResolvedVariant | LegacyVariant;
202
+
203
+ /** @deprecated Maps legacy variant names to current ones. */
204
+ const legacyVariantMap: Record<LegacyVariant, ResolvedVariant> = {
205
+ primary: "strong",
206
+ secondary: "moderate",
207
+ warning: "moderate",
208
+ destructive: "unranked",
209
+ outline: "unranked",
210
+ };
211
+
212
+ function isLegacyVariant(v: string): v is LegacyVariant {
213
+ return v in legacyVariantMap;
214
+ }
215
+
216
+ function resolveVariant(variant: MapGridPinVariant): ResolvedVariant {
217
+ return isLegacyVariant(variant) ? legacyVariantMap[variant] : variant;
218
+ }
219
+
220
+ /**
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.
224
+ */
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",
53
231
  };
54
232
 
233
+ const mapGridPinVariants = cva(
234
+ "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
+ {
236
+ variants: {
237
+ variant: {
238
+ strong: `${mapGridPinColorMap.strong}`,
239
+ moderate: `${mapGridPinColorMap.moderate}`,
240
+ weak: `${mapGridPinColorMap.weak}`,
241
+ unranked: `${mapGridPinColorMap.unranked} text-white dark:text-white`,
242
+ error: `${mapGridPinColorMap.error}`,
243
+ },
244
+ },
245
+ defaultVariants: {
246
+ variant: "strong",
247
+ },
248
+ }
249
+ );
250
+
55
251
  /**
56
252
  * Props for the MapGridPin component.
57
253
  */
58
254
  interface MapGridPinProps extends Omit<
59
- React.ComponentProps<"button">,
60
- "children" | "type"
255
+ React.ComponentProps<"div">,
256
+ "children"
61
257
  > {
62
258
  /** Value displayed inside the pin (number or short label) */
63
259
  value: number | string;
64
- /** Button variant — consumer controls this based on value thresholds */
260
+ /** Color variant — consumer controls this based on value thresholds */
65
261
  variant?: MapGridPinVariant;
66
- /** Enable infinite pulse animation radiating from the pin */
262
+ /** Show loading appearance (neutral styling, overrides variant colors) */
263
+ loading?: boolean;
264
+ /**
265
+ * @deprecated No longer rendered. Kept for backward compatibility.
266
+ */
67
267
  pulse?: boolean;
68
268
  /** Required test hook identifier */
69
269
  dataHook: string;
@@ -74,50 +274,57 @@ interface MapGridPinProps extends Omit<
74
274
  }
75
275
 
76
276
  /**
77
- * A circular map pin button that displays a numeric value with a colored background.
78
- * Uses the Button component internally. Color is determined by the `variant` prop —
79
- * the consumer controls which variant to apply based on the value.
80
- * Supports an optional `pulse` animation for emphasis.
277
+ * A circular map pin that displays a numeric value with a colored background.
278
+ * Renders as a non-focusable `div` (compatible with Google Maps AdvancedMarkerElement).
279
+ * Color is determined by the `variant` prop — the consumer controls which variant
280
+ * to apply based on the value.
81
281
  */
82
- const MapGridPin = React.forwardRef<HTMLButtonElement, MapGridPinProps>(
282
+ const MapGridPin = React.forwardRef<HTMLDivElement, MapGridPinProps>(
83
283
  (
84
284
  {
85
285
  value,
86
- variant = "primary",
87
- pulse = false,
286
+ variant: variantProp = "strong",
287
+ loading = false,
288
+ pulse: _pulse, // eslint-disable-line @typescript-eslint/no-unused-vars -- absorbed from ...props to prevent DOM passthrough
88
289
  dataHook,
89
290
  className,
90
291
  trackingEl,
91
292
  trackingLabel,
293
+ style,
92
294
  ...props
93
295
  },
94
296
  ref
95
297
  ) => {
298
+ const variant = resolveVariant(variantProp);
299
+
96
300
  return (
97
- <Button
301
+ <div
98
302
  ref={ref}
99
303
  className={cn(
304
+ loading
305
+ ? "border-border bg-accent rounded-full border"
306
+ : mapGridPinVariants({ variant }),
100
307
  "size-8 p-0",
101
- pulse &&
102
- "animate-grid-pin-pulse transition-none motion-reduce:animate-none",
103
308
  className
104
309
  )}
105
- dataHook={dataHook}
106
- size="sm"
107
- style={
108
- pulse
109
- ? ({
110
- "--grid-pin-pulse-color": gridPinPulseVar[variant],
111
- } as React.CSSProperties)
112
- : undefined
113
- }
114
- trackingEl={trackingEl || "map-grid-pin"}
115
- trackingLabel={trackingLabel}
116
- variant={variant}
310
+ data-hook={dataHook}
311
+ data-slot="map-grid-pin"
312
+ data-state={loading ? "loading" : undefined}
313
+ data-tracking-el={trackingEl || "map-grid-pin"}
314
+ data-tracking-label={trackingLabel}
315
+ style={style}
117
316
  {...props}
118
317
  >
119
- {String(value)}
120
- </Button>
318
+ {variant === "error" && !loading ? (
319
+ <TriangleAlert
320
+ aria-hidden="true"
321
+ className="text-warning-foreground"
322
+ size={14}
323
+ />
324
+ ) : (
325
+ String(value)
326
+ )}
327
+ </div>
121
328
  );
122
329
  }
123
330
  );
@@ -131,20 +338,135 @@ MapGridPin.displayName = "MapGridPin";
131
338
  /**
132
339
  * Props for the MapLocationPin component.
133
340
  */
134
- interface MapLocationPinProps extends Omit<MapGridPinProps, "value"> {
135
- /** Numeric value displayed inside the pin */
341
+ interface MapLocationPinProps extends Omit<
342
+ React.ComponentProps<"div">,
343
+ "children"
344
+ > {
345
+ /** Icon rendered inside the pin marker @default Store icon */
346
+ icon?: React.ReactNode;
347
+ /** Play a one-time entrance — the pin springs into place from its anchor point when it mounts @default false */
348
+ animateIn?: boolean;
349
+ /** Required test hook identifier */
350
+ dataHook: string;
351
+ /** Analytics element identifier */
352
+ trackingEl?: string;
353
+ /** Analytics label */
354
+ trackingLabel?: string;
355
+ /**
356
+ * Accessible label for the pin marker.
357
+ * @default "Location"
358
+ */
359
+ ariaLabel?: string;
360
+ /**
361
+ * Numeric value displayed inside the pin.
362
+ * @deprecated Use {@link MapGridPin} for numbered pins. Provided only for
363
+ * backward compatibility — passing it renders the legacy numbered-circle marker.
364
+ */
136
365
  value?: number;
366
+ /**
367
+ * Colour variant for the legacy numbered pin.
368
+ * @deprecated Use {@link MapGridPin} for numbered pins. Provided only for
369
+ * backward compatibility — passing it renders the legacy numbered-circle marker.
370
+ */
371
+ variant?: MapGridPinVariant;
372
+ /**
373
+ * Enable the legacy pulse animation. Prefer {@link MapLocationPinProps.animateIn}
374
+ * for the teardrop entrance.
375
+ * @deprecated Use {@link MapGridPin} for numbered pins. Provided only for
376
+ * backward compatibility — passing it renders the legacy numbered-circle marker.
377
+ */
378
+ pulse?: boolean;
137
379
  }
138
380
 
139
381
  /**
140
- * A map location pin marker.
141
- * Thin wrapper around MapGridPin with a default value of 1.
382
+ * A teardrop-shaped map location pin with an icon inside.
383
+ * Renders an SVG pin marker with a circular icon area and drop shadow.
142
384
  * Designed to be placed inside any map marker component (e.g. AdvancedMarker).
385
+ *
386
+ * Backward compatibility: the previously published `MapLocationPin` was a thin
387
+ * wrapper around {@link MapGridPin} (a numbered circle). Passing any legacy prop
388
+ * (`value`, `variant`, or `pulse`) renders that original numbered-pin marker so
389
+ * existing consumers keep working; otherwise the new teardrop marker is rendered.
143
390
  */
144
- const MapLocationPin = React.forwardRef<HTMLButtonElement, MapLocationPinProps>(
145
- ({ value = 1, dataHook, ...props }, ref) => {
391
+ const MapLocationPin = React.forwardRef<HTMLDivElement, MapLocationPinProps>(
392
+ (
393
+ {
394
+ icon,
395
+ animateIn = false,
396
+ value,
397
+ variant,
398
+ pulse,
399
+ dataHook,
400
+ className,
401
+ trackingEl,
402
+ trackingLabel,
403
+ ariaLabel,
404
+ ...props
405
+ },
406
+ ref
407
+ ) => {
408
+ // Backward compatibility: the previously published MapLocationPin was a thin
409
+ // wrapper around MapGridPin (a numbered circle). If any legacy prop is
410
+ // supplied, preserve that exact behaviour so existing consumers keep working.
411
+ if (value !== undefined || variant !== undefined || pulse !== undefined) {
412
+ return (
413
+ <MapGridPin
414
+ ref={ref}
415
+ className={className}
416
+ dataHook={dataHook}
417
+ pulse={pulse}
418
+ trackingEl={trackingEl}
419
+ trackingLabel={trackingLabel}
420
+ value={value ?? 1}
421
+ variant={variant}
422
+ {...props}
423
+ />
424
+ );
425
+ }
426
+
427
+ // Rendered as a non-focusable `div` (compatible with Google Maps
428
+ // AdvancedMarkerElement), with role="img" so the icon marker has an
429
+ // accessible name.
146
430
  return (
147
- <MapGridPin ref={ref} dataHook={dataHook} value={value} {...props} />
431
+ <div
432
+ ref={ref}
433
+ aria-label={ariaLabel ?? "Location"}
434
+ className={cn(
435
+ "relative inline-flex h-[46px] w-[38px] items-start justify-center",
436
+ className
437
+ )}
438
+ data-hook={dataHook}
439
+ data-slot="map-location-pin"
440
+ data-tracking-el={trackingEl || "map-location-pin"}
441
+ data-tracking-label={trackingLabel}
442
+ role="img"
443
+ {...props}
444
+ >
445
+ <span
446
+ aria-hidden="true"
447
+ className={cn(
448
+ "relative flex size-full",
449
+ animateIn &&
450
+ "animate-pop-in origin-bottom will-change-transform motion-reduce:animate-none"
451
+ )}
452
+ >
453
+ <svg
454
+ aria-hidden="true"
455
+ className="size-full overflow-visible drop-shadow-sm"
456
+ fill="none"
457
+ viewBox="0 0 38 46"
458
+ >
459
+ <path
460
+ className="fill-white"
461
+ d="M38 19.15C38 29.21 29.4 35.77 20.38 44.63C19.61 45.39 18.37 45.41 17.58 44.67C8.01 35.79 0 29.23 0 19.15C0 8.57 8.51 0 19 0C29.49 0 38 8.57 38 19.15Z"
462
+ />
463
+ <circle className="fill-sky-500" cx="19" cy="19" r="16" />
464
+ </svg>
465
+ <span className="absolute top-[19px] left-1/2 flex -translate-x-1/2 -translate-y-1/2 items-center justify-center text-white">
466
+ {icon ?? <Store size={16} />}
467
+ </span>
468
+ </span>
469
+ </div>
148
470
  );
149
471
  }
150
472
  );
@@ -170,11 +492,15 @@ interface MapControlButtonProps extends Omit<
170
492
  trackingLabel?: string;
171
493
  /** Button type attribute */
172
494
  type?: "button" | "submit";
495
+ /** Render as compact icon-only button or with text @default true */
496
+ iconOnly?: boolean;
173
497
  }
174
498
 
175
499
  /**
176
500
  * A floating control button for map UIs.
177
- * Renders a square, shadowed button designed to overlay a map surface.
501
+ * Uses `outline` in light mode and `secondary` in dark mode.
502
+ * In icon-only mode (default) renders a circular icon button.
503
+ * With `iconOnly={false}` renders a pill-shaped button with text and icon.
178
504
  * Use for zoom, locate, layer toggles, and other map controls.
179
505
  */
180
506
  const MapControlButton = React.forwardRef<
@@ -182,18 +508,29 @@ const MapControlButton = React.forwardRef<
182
508
  MapControlButtonProps
183
509
  >(
184
510
  (
185
- { className, dataHook, trackingEl, trackingLabel, children, ...props },
511
+ {
512
+ className,
513
+ dataHook,
514
+ trackingEl,
515
+ trackingLabel,
516
+ children,
517
+ iconOnly = true,
518
+ ...props
519
+ },
186
520
  ref
187
521
  ) => {
522
+ const isDark = useIsDarkMode();
523
+
188
524
  return (
189
525
  <Button
190
526
  ref={ref}
191
- className={cn("rounded-lg shadow-sm", className)}
527
+ className={className}
192
528
  data-slot="map-control-button"
193
529
  dataHook={dataHook}
530
+ iconOnly={iconOnly}
194
531
  trackingEl={trackingEl || "map-control-button"}
195
532
  trackingLabel={trackingLabel}
196
- variant="outline"
533
+ variant={isDark ? "secondary" : "outline"}
197
534
  {...props}
198
535
  >
199
536
  {children}
@@ -212,29 +549,36 @@ MapControlButton.displayName = "MapControlButton";
212
549
  * Props for the MapLoadingState component.
213
550
  */
214
551
  interface MapLoadingStateProps extends React.ComponentProps<"div"> {
215
- /** Optional loading message */
216
- message?: string;
552
+ /** Content displayed centered over the map background */
553
+ children?: React.ReactNode;
217
554
  /** Required test hook identifier */
218
555
  dataHook: string;
219
556
  /** Analytics element identifier */
220
557
  trackingEl?: string;
221
558
  /** Analytics label */
222
559
  trackingLabel?: string;
560
+ /**
561
+ * Accessible label for the loading status region.
562
+ * @default "Loading map"
563
+ */
564
+ ariaLabel?: string;
223
565
  }
224
566
 
225
567
  /**
226
568
  * A loading placeholder for map containers.
227
- * Uses the same spinner pattern as ComboboxLoading.
228
- * Use as a fallback while the map provider is loading.
569
+ * Displays the map background image with consumer-provided content
570
+ * centered vertically and horizontally. Fills its parent container.
571
+ * Use as a fallback while the map provider is initialising.
229
572
  */
230
573
  const MapLoadingState = React.forwardRef<HTMLDivElement, MapLoadingStateProps>(
231
574
  (
232
575
  {
233
576
  className,
234
- message = "Loading map…",
577
+ children,
235
578
  dataHook,
236
579
  trackingEl,
237
580
  trackingLabel,
581
+ ariaLabel,
238
582
  ...props
239
583
  },
240
584
  ref
@@ -242,9 +586,9 @@ const MapLoadingState = React.forwardRef<HTMLDivElement, MapLoadingStateProps>(
242
586
  return (
243
587
  <div
244
588
  ref={ref}
245
- aria-live="polite"
589
+ aria-label={ariaLabel ?? "Loading map"}
246
590
  className={cn(
247
- "text-muted-foreground flex items-center justify-center gap-2 py-6 text-sm",
591
+ "border-border relative flex h-full w-full items-center justify-center overflow-hidden rounded-lg border",
248
592
  className
249
593
  )}
250
594
  data-hook={dataHook}
@@ -254,11 +598,8 @@ const MapLoadingState = React.forwardRef<HTMLDivElement, MapLoadingStateProps>(
254
598
  role="status"
255
599
  {...props}
256
600
  >
257
- <div
258
- aria-hidden="true"
259
- className="size-4 animate-spin rounded-full border-2 border-current border-t-transparent"
260
- />
261
- {message}
601
+ <MapBackground />
602
+ {children && <div className="relative">{children}</div>}
262
603
  </div>
263
604
  );
264
605
  }
@@ -266,6 +607,27 @@ const MapLoadingState = React.forwardRef<HTMLDivElement, MapLoadingStateProps>(
266
607
 
267
608
  MapLoadingState.displayName = "MapLoadingState";
268
609
 
610
+ // ──────────────────────────────────────
611
+ // MapBackground (internal)
612
+ // ──────────────────────────────────────
613
+
614
+ const MapBackground = React.memo(function MapBackground({
615
+ rounded,
616
+ }: {
617
+ rounded?: boolean;
618
+ }) {
619
+ return (
620
+ <MapBackgroundImage
621
+ aria-hidden="true"
622
+ className={cn(
623
+ "absolute inset-0 h-full w-full object-cover",
624
+ rounded && "rounded-[inherit]"
625
+ )}
626
+ mode="auto"
627
+ />
628
+ );
629
+ });
630
+
269
631
  // ──────────────────────────────────────
270
632
  // MapErrorState
271
633
  // ──────────────────────────────────────
@@ -274,12 +636,31 @@ MapLoadingState.displayName = "MapLoadingState";
274
636
  * Props for the MapErrorState component.
275
637
  */
276
638
  interface MapErrorStateProps extends React.ComponentProps<"div"> {
277
- /** Error title */
639
+ /**
640
+ * Error title displayed as a heading.
641
+ * @default "We couldn't load your map rankings."
642
+ */
278
643
  title?: string;
279
- /** Error description */
644
+ /**
645
+ * Error description displayed below the title.
646
+ * @default "Reloading usually fixes it, and it won't use any credits"
647
+ */
280
648
  message?: string;
281
- /** Retry callback — renders a "Try again" button when provided */
649
+ /**
650
+ * Retry callback. When provided, renders a retry button.
651
+ * Omit to hide the retry button entirely.
652
+ */
282
653
  onRetry?: () => void;
654
+ /**
655
+ * Show the retry button in its loading state while the map reloads.
656
+ * @default false
657
+ */
658
+ retryLoading?: boolean;
659
+ /**
660
+ * Label for the retry button.
661
+ * @default "Reload"
662
+ */
663
+ retryLabel?: string;
283
664
  /** Required test hook identifier */
284
665
  dataHook: string;
285
666
  /** Analytics element identifier */
@@ -290,16 +671,18 @@ interface MapErrorStateProps extends React.ComponentProps<"div"> {
290
671
 
291
672
  /**
292
673
  * An error state for map containers.
293
- * Displays an alert icon, title, message, and an optional retry button.
294
- * Use when the map provider fails to initialise or a network error occurs.
674
+ * Displays the Globey "fixing fault" illustration, title, and message.
675
+ * Pass `onRetry` to render a retry button; omit it to hide the button entirely.
295
676
  */
296
677
  const MapErrorState = React.forwardRef<HTMLDivElement, MapErrorStateProps>(
297
678
  (
298
679
  {
299
680
  className,
300
- title = "Unable to load map",
301
- message = "Something went wrong while loading the map. Please try again.",
681
+ title = "We couldn't load your map rankings.",
682
+ message = "Reloading usually fixes it, and it won't use any credits",
302
683
  onRetry,
684
+ retryLoading = false,
685
+ retryLabel = "Reload",
303
686
  dataHook,
304
687
  trackingEl,
305
688
  trackingLabel,
@@ -311,7 +694,7 @@ const MapErrorState = React.forwardRef<HTMLDivElement, MapErrorStateProps>(
311
694
  <div
312
695
  ref={ref}
313
696
  className={cn(
314
- "bg-muted/50 flex flex-col items-center justify-center gap-3 rounded-xl p-8 text-center",
697
+ "border-border relative flex h-full w-full flex-col items-center justify-center gap-4 rounded-lg border p-4 text-center sm:gap-6 sm:p-8",
315
698
  className
316
699
  )}
317
700
  data-hook={dataHook}
@@ -321,39 +704,45 @@ const MapErrorState = React.forwardRef<HTMLDivElement, MapErrorStateProps>(
321
704
  role="alert"
322
705
  {...props}
323
706
  >
324
- <AlertCircle
325
- aria-hidden="true"
326
- className="text-muted-foreground/60"
327
- size={40}
328
- strokeWidth={1.5}
329
- />
330
- <div className="flex flex-col gap-1">
331
- <h3
332
- className="text-foreground text-sm font-semibold"
333
- data-slot="map-error-title"
707
+ <MapBackground rounded />
708
+ <div className="relative flex flex-col items-center gap-4 sm:gap-6">
709
+ <div
710
+ aria-hidden="true"
711
+ className="flex items-center justify-center"
712
+ data-slot="map-error-illustration"
334
713
  >
335
- {title}
336
- </h3>
337
- {message && (
338
- <p
339
- className="text-muted-foreground max-w-xs text-xs"
340
- data-slot="map-error-message"
714
+ <GlobeyFixingFault className="h-auto w-full max-w-41" />
715
+ </div>
716
+ <div className="flex flex-col gap-2">
717
+ <h3
718
+ className="text-foreground text-lg font-medium"
719
+ data-slot="map-error-title"
341
720
  >
342
- {message}
343
- </p>
721
+ {title}
722
+ </h3>
723
+ {message && (
724
+ <p
725
+ className="text-muted-foreground text-sm"
726
+ data-slot="map-error-message"
727
+ >
728
+ {message}
729
+ </p>
730
+ )}
731
+ </div>
732
+ {onRetry && (
733
+ <Button
734
+ className="mt-1"
735
+ dataHook={`${dataHook}-retry`}
736
+ loading={retryLoading}
737
+ size="sm"
738
+ variant="primary"
739
+ onClick={onRetry}
740
+ >
741
+ {!retryLoading && <RefreshCw aria-hidden="true" />}
742
+ {retryLabel}
743
+ </Button>
344
744
  )}
345
745
  </div>
346
- {onRetry && (
347
- <Button
348
- className="mt-1"
349
- dataHook={`${dataHook}-retry`}
350
- size="sm"
351
- variant="primary"
352
- onClick={onRetry}
353
- >
354
- Try again
355
- </Button>
356
- )}
357
746
  </div>
358
747
  );
359
748
  }
@@ -361,6 +750,60 @@ const MapErrorState = React.forwardRef<HTMLDivElement, MapErrorStateProps>(
361
750
 
362
751
  MapErrorState.displayName = "MapErrorState";
363
752
 
753
+ // ──────────────────────────────────────
754
+ // MapLegendItem
755
+ // ──────────────────────────────────────
756
+
757
+ /**
758
+ * Props for the MapLegendItem component.
759
+ */
760
+ interface MapLegendItemProps extends React.ComponentProps<"span"> {
761
+ /**
762
+ * Pin ranking variant — resolves to the matching MapGridPin background color.
763
+ * Preferred over `color` so pin and legend stay in sync automatically.
764
+ */
765
+ variant?: ResolvedVariant;
766
+ /**
767
+ * Dot color as a Tailwind background class (e.g. "bg-primary").
768
+ * Use for non-ranking legends where no pin variant applies.
769
+ * Ignored when `variant` is provided.
770
+ */
771
+ color?: string;
772
+ /** Required test hook identifier */
773
+ dataHook: string;
774
+ }
775
+
776
+ /**
777
+ * A single legend entry: colored dot + label text.
778
+ * Pass `variant` to match MapGridPin colors automatically, or `color` for custom dots.
779
+ */
780
+ const MapLegendItem = React.forwardRef<HTMLSpanElement, MapLegendItemProps>(
781
+ ({ variant, color, dataHook, className, children, ...props }, ref) => {
782
+ const dotColor = variant ? mapGridPinColorMap[variant] : color;
783
+
784
+ return (
785
+ <span
786
+ ref={ref}
787
+ className={cn(
788
+ "text-foreground flex items-center gap-1 font-sans text-xs",
789
+ className
790
+ )}
791
+ data-hook={dataHook}
792
+ data-slot="map-legend-item"
793
+ {...props}
794
+ >
795
+ <span
796
+ aria-hidden="true"
797
+ className={cn("inline-block size-2 shrink-0 rounded-full", dotColor)}
798
+ />
799
+ {children}
800
+ </span>
801
+ );
802
+ }
803
+ );
804
+
805
+ MapLegendItem.displayName = "MapLegendItem";
806
+
364
807
  // ──────────────────────────────────────
365
808
  // MapLegend
366
809
  // ──────────────────────────────────────
@@ -375,6 +818,11 @@ interface MapLegendProps extends React.ComponentProps<"div"> {
375
818
  trackingEl?: string;
376
819
  /** Analytics label */
377
820
  trackingLabel?: string;
821
+ /**
822
+ * Accessible label for the legend group.
823
+ * @default "Map legend"
824
+ */
825
+ ariaLabel?: string;
378
826
  }
379
827
 
380
828
  /**
@@ -383,20 +831,33 @@ interface MapLegendProps extends React.ComponentProps<"div"> {
383
831
  */
384
832
  const MapLegend = React.forwardRef<HTMLDivElement, MapLegendProps>(
385
833
  (
386
- { className, dataHook, trackingEl, trackingLabel, children, ...props },
834
+ {
835
+ className,
836
+ dataHook,
837
+ trackingEl,
838
+ trackingLabel,
839
+ ariaLabel,
840
+ children,
841
+ ...props
842
+ },
387
843
  ref
388
844
  ) => {
389
845
  return (
390
846
  <Card
391
847
  ref={ref}
392
- className={cn("inline-flex w-auto flex-row items-center", className)}
848
+ aria-label={ariaLabel ?? "Map legend"}
849
+ className={cn(
850
+ "inline-flex w-auto flex-row items-center bg-white font-sans dark:bg-neutral-800",
851
+ className
852
+ )}
393
853
  data-slot="map-legend"
394
854
  dataHook={dataHook}
395
855
  density="condensed"
396
856
  maxWidth="none"
857
+ role="group"
397
858
  trackingEl={trackingEl || "map-legend"}
398
859
  trackingLabel={trackingLabel}
399
- variant="filled"
860
+ variant="border"
400
861
  {...props}
401
862
  >
402
863
  <CardContent className="flex items-center gap-3">
@@ -410,61 +871,132 @@ const MapLegend = React.forwardRef<HTMLDivElement, MapLegendProps>(
410
871
  MapLegend.displayName = "MapLegend";
411
872
 
412
873
  // ──────────────────────────────────────
413
- // useMapPopoverHover
874
+ // useMapPopoverClick
414
875
  // ──────────────────────────────────────
415
876
 
416
877
  /**
417
- * Return type of {@link useMapPopoverHover}.
878
+ * Options for {@link useMapPopoverClick}.
879
+ */
880
+ interface UseMapPopoverClickOptions {
881
+ /**
882
+ * When `true`, hovering a pin switches the popover to that pin
883
+ * after any pin has been clicked open (menubar-style interaction).
884
+ * Mouse-only — touch events are filtered out.
885
+ * @default false
886
+ */
887
+ hoverWhenOpen?: boolean;
888
+ }
889
+
890
+ /**
891
+ * Pointer interaction props returned by {@link UseMapPopoverClickReturn.getInteractionProps}.
418
892
  */
419
- interface UseMapPopoverHoverReturn<T> {
420
- /** The item currently being hovered, or `null` when idle. Use for `open` prop. */
893
+ interface MapPinInteractionProps {
894
+ onClick: () => void;
895
+ onPointerEnter?: (e: React.PointerEvent) => void;
896
+ }
897
+
898
+ /**
899
+ * Return type of {@link useMapPopoverClick}.
900
+ */
901
+ interface UseMapPopoverClickReturn<T> {
902
+ /** The item whose popover is open, or `null` when closed. */
421
903
  activeItem: T | null;
422
- /** Last non-null item — holds position stable during the close animation. Use for anchor positioning. */
904
+ /** Last non-null item — holds position stable during the close animation. */
423
905
  anchorItem: T | null;
424
- /** Set a new active item and cancel any pending close timer. */
906
+ /** Open the popover for the given item. If another item is active, switches instantly. */
425
907
  showItem: (item: T) => void;
426
- /** Start a delayed close (default 150 ms). Moving to another pin or the popover content cancels it. */
427
- scheduleClose: () => void;
428
- /** Cancel a pending close — call from `MapPopoverContent.onMouseEnter`. */
429
- cancelClose: () => void;
908
+ /** Close the popover. */
909
+ close: () => void;
910
+ /**
911
+ * Returns event handler props for a pin.
912
+ * Always includes `onClick`; includes `onPointerEnter` when `hoverWhenOpen` is enabled.
913
+ * Spread onto the marker element or pass individual handlers.
914
+ */
915
+ getInteractionProps: (item: T) => MapPinInteractionProps;
430
916
  }
431
917
 
432
918
  /**
433
- * Manages hover state for a single repositioning Popover on dense map grids.
919
+ * Manages click-to-open state for a single map popover.
920
+ *
921
+ * Designed for use with Google Maps `AdvancedMarker` — register `onClick`
922
+ * on the `AdvancedMarker` component (not on child DOM elements) to avoid the
923
+ * "Focusable child elements in AdvancedMarkerElement are not supported" warning.
924
+ *
925
+ * Pass `{ hoverWhenOpen: true }` to enable menubar-style interaction:
926
+ * the first pin requires a click, but subsequent pins switch on hover.
927
+ * Only mouse pointers trigger hover — touch is filtered out.
928
+ *
929
+ * @example
930
+ * ```tsx
931
+ * const { activeItem, anchorItem, showItem, close } = useMapPopoverClick<Pin>();
932
+ *
933
+ * <Map onClick={close}>
934
+ * <AdvancedMarker position={pin} onClick={() => showItem(pin)}>
935
+ * <MapGridPin dataHook="pin" value={pin.rank} />
936
+ * </AdvancedMarker>
937
+ * </Map>
938
+ *
939
+ * <MapPopover open={!!activeItem}>
940
+ * <MapPopoverAnchor ... />
941
+ * <MapPopoverContent dataHook="popover" onEscapeKeyDown={close}>
942
+ * {activeItem && <p>{activeItem.rank}</p>}
943
+ * </MapPopoverContent>
944
+ * </MapPopover>
945
+ * ```
434
946
  *
435
- * Wire the returned callbacks to `MapGridPin` mouse events and
436
- * `MapPopoverContent` mouse events. The 150 ms grace period prevents
437
- * flicker when the pointer travels between a pin and the popover content.
947
+ * @example
948
+ * ```tsx
949
+ * // With hoverWhenOpen — click first pin, then hover to switch
950
+ * const { activeItem, anchorItem, getInteractionProps, close } =
951
+ * useMapPopoverClick<Pin>({ hoverWhenOpen: true });
438
952
  *
439
- * @param delay - Close timer in ms.
440
- * @default 150
953
+ * <AdvancedMarker {...getInteractionProps(pin)}>
954
+ * <MapGridPin dataHook="pin" value={pin.rank} />
955
+ * </AdvancedMarker>
956
+ * ```
441
957
  */
442
- function useMapPopoverHover<T>(delay = 150): UseMapPopoverHoverReturn<T> {
958
+ function useMapPopoverClick<T>(
959
+ options?: UseMapPopoverClickOptions
960
+ ): UseMapPopoverClickReturn<T> {
961
+ const { hoverWhenOpen = false } = options ?? {};
962
+
443
963
  const [activeItem, setActiveItem] = React.useState<T | null>(null);
444
964
  const [anchorItem, setAnchorItem] = React.useState<T | null>(null);
445
- const timeoutRef = React.useRef<ReturnType<typeof setTimeout>>(null);
446
965
 
447
966
  const showItem = React.useCallback((item: T) => {
448
- if (timeoutRef.current) clearTimeout(timeoutRef.current);
449
967
  setAnchorItem(item);
450
968
  setActiveItem(item);
451
969
  }, []);
452
970
 
453
- const scheduleClose = React.useCallback(() => {
454
- if (timeoutRef.current) clearTimeout(timeoutRef.current);
455
- timeoutRef.current = setTimeout(() => setActiveItem(null), delay);
456
- }, [delay]);
457
-
458
- const cancelClose = React.useCallback(() => {
459
- if (timeoutRef.current) clearTimeout(timeoutRef.current);
971
+ const close = React.useCallback(() => {
972
+ setActiveItem(null);
460
973
  }, []);
461
974
 
975
+ const getInteractionProps = React.useCallback(
976
+ (item: T): MapPinInteractionProps => {
977
+ const props: MapPinInteractionProps = {
978
+ onClick: () => showItem(item),
979
+ };
980
+
981
+ if (hoverWhenOpen) {
982
+ props.onPointerEnter = (e: React.PointerEvent) => {
983
+ if (e.pointerType === "mouse" && activeItem != null) {
984
+ showItem(item);
985
+ }
986
+ };
987
+ }
988
+
989
+ return props;
990
+ },
991
+ [hoverWhenOpen, showItem, activeItem]
992
+ );
993
+
462
994
  return {
463
995
  activeItem,
464
996
  anchorItem,
465
997
  showItem,
466
- scheduleClose,
467
- cancelClose,
998
+ close,
999
+ getInteractionProps,
468
1000
  };
469
1001
  }
470
1002
 
@@ -521,11 +1053,15 @@ interface MapPopoverContentProps extends PopoverContentProps {
521
1053
 
522
1054
  /**
523
1055
  * Popover content panel with map-specific defaults.
524
- * Compact sizing (`w-auto p-3`), top placement, and focus-prevention
525
- * for hover-activated popovers.
1056
+ * Compact sizing (`w-auto max-w-68.25 p-3` — sizes to content, max 273px), top placement, and auto-focus prevention
1057
+ * for click-activated map popovers.
1058
+ *
1059
+ * Both `onOpenAutoFocus` and `onCloseAutoFocus` are prevented by default
1060
+ * to keep focus on the map surface. Override via props if standard
1061
+ * focus-return behavior is needed.
526
1062
  *
527
1063
  * Use inside a controlled `<MapPopover open={!!activeItem}>` together
528
- * with `MapPopoverAnchor` and {@link useMapPopoverHover}.
1064
+ * with `MapPopoverAnchor` and {@link useMapPopoverClick}.
529
1065
  */
530
1066
  const MapPopoverContent = React.forwardRef<
531
1067
  React.ComponentRef<typeof PopoverContent>,
@@ -546,7 +1082,7 @@ const MapPopoverContent = React.forwardRef<
546
1082
  <PopoverContent
547
1083
  ref={ref}
548
1084
  className={cn(
549
- "w-auto p-3 data-[state=closed]:animate-none data-[state=closed]:opacity-0",
1085
+ "w-auto max-w-68.25 p-3 data-[state=closed]:animate-none data-[state=closed]:opacity-0",
550
1086
  className
551
1087
  )}
552
1088
  data-slot="map-popover-content"
@@ -555,6 +1091,7 @@ const MapPopoverContent = React.forwardRef<
555
1091
  dataHook={dataHook}
556
1092
  side={side}
557
1093
  sideOffset={sideOffset}
1094
+ onCloseAutoFocus={(e) => e.preventDefault()}
558
1095
  onOpenAutoFocus={(e) => e.preventDefault()}
559
1096
  {...props}
560
1097
  />
@@ -568,21 +1105,28 @@ MapPopoverContent.displayName = "MapPopoverContent";
568
1105
  // ──────────────────────────────────────
569
1106
 
570
1107
  export {
1108
+ MAP_STYLES,
571
1109
  MapTypeId,
572
1110
  MapLocationPin,
573
1111
  MapGridPin,
1112
+ mapGridPinColorMap,
574
1113
  MapControlButton,
575
1114
  MapLoadingState,
576
1115
  MapErrorState,
577
1116
  MapLegend,
1117
+ MapLegendItem,
578
1118
  MapPopover,
579
1119
  MapPopoverAnchor,
580
1120
  MapPopoverContent,
581
- useMapPopoverHover,
1121
+ useMapStyles,
1122
+ useMapPopoverClick,
582
1123
  };
583
1124
 
584
1125
  export type {
1126
+ MapStyleVariant,
1127
+ MapStyleRule,
585
1128
  MapTypeIdValue,
1129
+ ResolvedVariant as MapPinVariant,
586
1130
  MapLocationPinProps,
587
1131
  MapGridPinProps,
588
1132
  MapGridPinVariant,
@@ -590,8 +1134,11 @@ export type {
590
1134
  MapLoadingStateProps,
591
1135
  MapErrorStateProps,
592
1136
  MapLegendProps,
1137
+ MapLegendItemProps,
593
1138
  MapPopoverProps,
594
1139
  MapPopoverAnchorProps,
595
1140
  MapPopoverContentProps,
596
- UseMapPopoverHoverReturn,
1141
+ UseMapPopoverClickOptions,
1142
+ UseMapPopoverClickReturn,
1143
+ MapPinInteractionProps,
597
1144
  };