feat: updated AdvancedMarker anchoring implementation (#841)

* fix: make pointer events more robust

* feat(advanced-marker): add anchorLeft and anchorTop props

Adds support for the 'anchorLeft' and 'anchorTop' properties on the AdvancedMarker component. This provides a more direct way to control the anchor point of the marker, especially with modern versions of the Google Maps JavaScript API.

The implementation includes:
- A new internal 'useAdvancedMarkerAnchorPoint' hook to encapsulate anchoring logic.
- Version detection to use native 'anchorLeft'/'anchorTop' properties on Google Maps API v3.62+ and fallback to a CSS transform on older versions.
- A warning is logged when using the new props on unsupported API versions.
- Added TypeScript definitions of anchor options to type augmentation
- Added API documentation.

* test(advanced-marker): add anchor prop tests

Adds a suite of tests for the anchor-related props ('anchorLeft', 'anchorTop', and 'anchorPoint') on the AdvancedMarker component.

This suite covers:
- Precedence of 'anchorLeft'/'anchorTop' over 'anchorPoint' on modern APIs.
- Correct fallback to 'anchorPoint' on modern APIs.
- Correct application of 'anchorPoint' via CSS transform on legacy APIs.
- Warning generation when using modern props on legacy APIs.
- Snapshot testing for console warnings.

* feat(advanced-marker): deprecate anchorPoint prop

Marks the 'anchorPoint' prop as deprecated in favor of the 'anchorLeft' and 'anchorTop' props.

- Adds a '@deprecated' JSDoc tag to the 'anchorPoint' prop.
- Adds a TODO comment to add a console warning in a future version.

* fix: restrict event-handling hacks to custom anchoring

---------

Co-authored-by: Martin Schuhfuss <[email protected]>

Author: mrMetalWood

docs/api-reference/components/advanced-marker.md

@@ -173,6 +173,25 @@ The position is measured from the top-left corner and
 can be anything that can be consumed by a CSS translate() function.
 For example in percent `[10%, 90%]` or in pixels `[10px, 20px]`.
 
+#### `anchorLeft`: string
+
+A [CSS length-percentage] value which is used to translate the marker
+content relative to the anchor point. A value of 0 means the anchor-point
+will be at the left edge of the content-element. The default value is `-%50`,
+so the anchor point will be at the center of the content element.
+You can also use CSS `calc()` expressions to combine percentage and pixel
+values.
+
+#### `anchorTop`: string
+
+A [CSS length-percentage] value which is used to translate the marker content
+relative to the anchor point. When this value is 0, the anchor-point will be
+at the top-edge of the content element. The default value is `-%100`, which
+places the anchor-point at the bottom edge. You can also use CSS `calc()`
+expressions to combine percentage and pixel values.
+
+[CSS length-percentage]: https://developer.mozilla.org/en-US/docs/Web/CSS/length-percentage
+
 ### Other Props
 
 #### `clickable`: boolean

examples/advanced-marker-interaction/src/app.tsx

@@ -13,10 +13,10 @@ import {
   CollisionBehavior
 } from '@vis.gl/react-google-maps';
 
-import {getData} from './data';
-
 import ControlPanel from './control-panel';
 
+import {getData, MarkerType, textSnippets} from './data';
+
 import './style.css';
 
 export type AnchorPointName = keyof typeof AdvancedMarkerAnchorPoint;
@@ -27,7 +27,10 @@ export type AnchorPointName = keyof typeof AdvancedMarkerAnchorPoint;
 // thus appear in front.
 const data = getData()
   .sort((a, b) => b.position.lat - a.position.lat)
-  .map((dataItem, index) => ({...dataItem, zIndex: index}));
+  .map((dataItem, index) => ({
+    ...dataItem,
+    zIndex: index
+  }));
 
 const Z_INDEX_SELECTED = data.length;
 const Z_INDEX_HOVER = data.length + 1;
@@ -40,22 +43,33 @@ const App = () => {
 
   const [hoverId, setHoverId] = useState<string | null>(null);
   const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [infowindowContent, setInfowindowContent] = useState<string | null>(
+    null
+  );
 
-  const [anchorPoint, setAnchorPoint] = useState('BOTTOM' as AnchorPointName);
+  const [anchorPoint, setAnchorPoint] = useState(
+    'LEFT_CENTER' as AnchorPointName
+  );
   const [selectedMarker, setSelectedMarker] =
     useState<google.maps.marker.AdvancedMarkerElement | null>(null);
   const [infoWindowShown, setInfoWindowShown] = useState(false);
 
   const onMouseEnter = useCallback((id: string | null) => setHoverId(id), []);
   const onMouseLeave = useCallback(() => setHoverId(null), []);
   const onMarkerClick = useCallback(
-    (id: string | null, marker?: google.maps.marker.AdvancedMarkerElement) => {
+    (
+      id: string | null,
+      marker?: google.maps.marker.AdvancedMarkerElement,
+      type?: MarkerType
+    ) => {
       setSelectedId(id);
 
       if (marker) {
         setSelectedMarker(marker);
       }
 
+      setInfowindowContent(type ? textSnippets[type] : null);
+
       if (id !== selectedId) {
         setInfoWindowShown(true);
       } else {
@@ -97,12 +111,25 @@ const App = () => {
             zIndex = Z_INDEX_SELECTED;
           }
 
+          if (type === 'default') {
+            return (
+              <AdvancedMarkerWithRef
+                key={id}
+                zIndex={zIndex}
+                position={position}
+                onMarkerClick={marker => onMarkerClick(id, marker, type)}
+                onMouseEnter={() => onMouseEnter(id)}
+                onMouseLeave={onMouseLeave}
+              />
+            );
+          }
+
           if (type === 'pin') {
             return (
               <AdvancedMarkerWithRef
                 onMarkerClick={(
                   marker: google.maps.marker.AdvancedMarkerElement
-                ) => onMarkerClick(id, marker)}
+                ) => onMarkerClick(id, marker, type)}
                 onMouseEnter={() => onMouseEnter(id)}
                 onMouseLeave={onMouseLeave}
                 key={id}
@@ -114,7 +141,7 @@ const App = () => {
                 }}
                 position={position}>
                 <Pin
-                  background={selectedId === id ? '#22ccff' : null}
+                  background={selectedId === id ? '#22ccff' : 'orange'}
                   borderColor={selectedId === id ? '#1e89a1' : null}
                   glyphColor={selectedId === id ? '#0f677a' : null}
                 />
@@ -137,7 +164,9 @@ const App = () => {
                   }}
                   onMarkerClick={(
                     marker: google.maps.marker.AdvancedMarkerElement
-                  ) => onMarkerClick(id, marker)}
+                  ) => {
+                    onMarkerClick(id, marker, type);
+                  }}
                   onMouseEnter={() => onMouseEnter(id)}
                   collisionBehavior={
                     CollisionBehavior.OPTIONAL_AND_HIDES_LOWER_PRIORITY
@@ -166,11 +195,12 @@ const App = () => {
 
         {infoWindowShown && selectedMarker && (
           <InfoWindow
+            headerDisabled={true}
             anchor={selectedMarker}
             pixelOffset={[0, -2]}
             onCloseClick={handleInfowindowCloseClick}>
             <h2>Marker {selectedId}</h2>
-            <p>Some arbitrary html to be rendered into the InfoWindow.</p>
+            <p>{infowindowContent}</p>
           </InfoWindow>
         )}
       </Map>

examples/advanced-marker-interaction/src/data.ts

@@ -1,20 +1,32 @@
+export type MarkerType = 'default' | 'pin' | 'html';
+
 type MarkerData = Array<{
   id: string;
   position: google.maps.LatLngLiteral;
-  type: 'pin' | 'html';
+  type: MarkerType;
   zIndex: number;
+  infowindowContent?: string;
 }>;
 
+export const textSnippets = {
+  default: 'This is a default AdvancedMarkerElement without custom content',
+  pin: 'This is a AdvancedMarkerElement with custom pin-style marker',
+  html: 'This is a AdvancedMarkerElement with custom HTML content'
+} as const;
+
 export function getData() {
   const data: MarkerData = [];
 
   // create 50 random markers
   for (let index = 0; index < 50; index++) {
+    const type =
+      Math.random() < 0.1 ? 'default' : Math.random() < 0.5 ? 'pin' : 'html';
+
     data.push({
       id: String(index),
       position: {lat: rnd(53.52, 53.63), lng: rnd(9.88, 10.12)},
       zIndex: index,
-      type: Math.random() < 0.5 ? 'pin' : 'html'
+      type
     });
   }
 

examples/advanced-marker-interaction/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@vis.gl/react-google-maps": ["../../src"]
+    }
+  },
+  "include": ["src/**/*", "../../src/**/*", "./types/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

examples/advanced-marker-interaction/types/global.d.ts

@@ -0,0 +1,7 @@
+export declare global {
+  // const or let does not work in this case, it has to be var
+  // eslint-disable-next-line no-var
+  var GOOGLE_MAPS_API_KEY: string | undefined;
+  // eslint-disable-next-line no-var, @typescript-eslint/no-explicit-any
+  var process: any;
+}

src/components/__tests__/__snapshots__/advanced-marker.test.tsx.snap

@@ -0,0 +1,17 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`map and marker-library loaded anchoring with legacy API should warn when using anchorLeft/Top 1`] = `
+[
+  [
+    "AdvancedMarker: The anchorLeft and anchorTop props are only supported in Google Maps API version 3.62 and above. The current version is 3.61.0.",
+  ],
+]
+`;
+
+exports[`map and marker-library loaded anchoring with modern API anchorLeft/anchorTop should have precedence over anchorPoint 1`] = `
+[
+  [
+    "AdvancedMarker: the anchorPoint prop is ignored when anchorLeft and/or anchorTop are set.",
+  ],
+]
+`;

src/components/__tests__/advanced-marker.test.tsx

@@ -4,7 +4,7 @@ import {initialize, mockInstances} from '@googlemaps/jest-mocks';
 import {cleanup, queryByTestId, render} from '@testing-library/react';
 import '@testing-library/jest-dom';
 
-import {AdvancedMarker} from '../advanced-marker';
+import {AdvancedMarker, AdvancedMarkerAnchorPoint} from '../advanced-marker';
 import {useMap} from '../../hooks/use-map';
 import {useMapsLibrary} from '../../hooks/use-maps-library';
 
@@ -162,4 +162,95 @@ describe('map and marker-library loaded', () => {
 
   test.todo('marker should work with options');
   test.todo('marker should have a click listener');
+
+  describe('anchoring with modern API', () => {
+    beforeEach(() => {
+      google.maps.version = '3.62.9';
+    });
+
+    test('anchorLeft/anchorTop should have precedence over anchorPoint', async () => {
+      const consoleWarnSpy = jest
+        .spyOn(console, 'warn')
+        .mockImplementation(() => {});
+
+      render(
+        <AdvancedMarker
+          position={{lat: 0, lng: 0}}
+          anchorLeft={'10px'}
+          anchorTop={'20px'}
+          anchorPoint={['10%', '20%']}>
+          <div />
+        </AdvancedMarker>
+      );
+      const marker = await waitForMockInstance(
+        google.maps.marker.AdvancedMarkerElement
+      );
+
+      expect(marker.anchorLeft).toBe('10px');
+      expect(marker.anchorTop).toBe('20px');
+      expect(consoleWarnSpy.mock.calls).toMatchSnapshot();
+
+      consoleWarnSpy.mockRestore();
+    });
+
+    test('anchorPoint should be used as fallback', async () => {
+      render(
+        <AdvancedMarker
+          position={{lat: 0, lng: 0}}
+          anchorPoint={['12%', '34%']}>
+          <div />
+        </AdvancedMarker>
+      );
+      const marker = await waitForMockInstance(
+        google.maps.marker.AdvancedMarkerElement
+      );
+
+      expect(marker.anchorLeft).toBe('calc(-1 * 12%)');
+      expect(marker.anchorTop).toBe('calc(-1 * 34%)');
+    });
+  });
+
+  describe('anchoring with legacy API', () => {
+    beforeEach(() => {
+      google.maps.version = '3.61.0';
+    });
+
+    test('anchorPoint is applied as css transform', async () => {
+      render(
+        <AdvancedMarker
+          position={{lat: 0, lng: 0}}
+          anchorPoint={AdvancedMarkerAnchorPoint.CENTER}>
+          <div />
+        </AdvancedMarker>
+      );
+      const marker = await waitForMockInstance(
+        google.maps.marker.AdvancedMarkerElement
+      );
+
+      expect(marker.content).toBeInstanceOf(HTMLElement);
+      expect((marker.content as HTMLElement).style.transform).toBe(
+        'translate(50%, 100%) translate(calc(-1 * 50%), calc(-1 * 50%))'
+      );
+    });
+
+    test('should warn when using anchorLeft/Top', async () => {
+      const consoleWarnSpy = jest
+        .spyOn(console, 'warn')
+        .mockImplementation(() => {});
+
+      render(
+        <AdvancedMarker
+          position={{lat: 0, lng: 0}}
+          anchorLeft={'10px'}
+          anchorTop={'20px'}>
+          <div />
+        </AdvancedMarker>
+      );
+      await waitForMockInstance(google.maps.marker.AdvancedMarkerElement);
+
+      expect(consoleWarnSpy.mock.calls).toMatchSnapshot();
+
+      consoleWarnSpy.mockRestore();
+    });
+  });
 });