feat: add examples

examples/05.hover-styling.ts

@@ -0,0 +1,12 @@
+// title: marker interactivity: hover
+import {Marker} from './lib/marker';
+
+export default (map: google.maps.Map) => {
+  const marker = new Marker({
+    map,
+    position: {lat: 53.5, lng: 10}
+  });
+
+  marker.scale = ({marker}) => (marker.hovered ? 1.8 : 1.5);
+  marker.color = ({marker}) => (marker.hovered ? '#4285F4' : '#F4B400');
+};

examples/06.click-events.ts

@@ -0,0 +1,13 @@
+// title: marker interactivity: click events
+import {Marker} from './lib/marker';
+
+export default (map: google.maps.Map) => {
+  const marker = new Marker({
+    map,
+    position: {lat: 53.5, lng: 10}
+  });
+
+  marker.addListener('click', () => {
+    alert('yep, that marker was clicked');
+  });
+};

examples/07.mulitple-marker-single-select.ts

@@ -0,0 +1,47 @@
+// title: multiple markers / single selection
+import {Marker} from './lib/marker';
+
+function rnd(min: number, max: number) {
+  return min + Math.random() * (max - min);
+}
+
+export default (map: google.maps.Map) => {
+  const markers: Marker[] = [];
+  const bounds = new google.maps.LatLngBounds();
+
+  let selectedMarker: Marker | null = null;
+  const setSelected = (index: number) => {
+    if (selectedMarker !== null) {
+      selectedMarker.setData({selected: false});
+    }
+
+    const marker = markers[index];
+    marker.setData({selected: true});
+    selectedMarker = marker;
+  };
+
+  // create a couple of random markers
+  for (let i = 0; i < 10; i++) {
+    const position = {lat: rnd(53.5, 53.6), lng: rnd(9.9, 10.1)};
+    bounds.extend(position);
+
+    const marker = new Marker(
+      {
+        map,
+        position,
+        color: ({data}) => (data.selected ? '#DB4437' : '#4285F4')
+      },
+      // initial user-data
+      {selected: false}
+    );
+
+    marker.addListener('click', () => {
+      console.log('marker clicked:', marker);
+      setSelected(i);
+    });
+
+    markers.push(marker as Marker);
+  }
+
+  map.fitBounds(bounds);
+};

examples/examples.json

@@ -1 +1 @@
-{"00.default.ts":{"title":"00.default.ts","filename":"00.default.ts","source":"// Marker-API Example Playground\n//\n// Edit the code and hit CMD + Enter to execute it.\n//\n// Key bindings:\n//\n// <Cmd> + <Return>   compile typescript and execute\n// <Cmd> + <S>        save the code to the URL\n//\n\nimport {Marker} from './lib/marker';\nimport {MaterialIcons} from './lib/icons';\n\nexport default (map: google.maps.Map) => {\n  Marker.registerIconProvider(MaterialIcons());\n\n  const m1 = new Marker();\n  m1.position = {lat: 53.555, lng: 10.001};\n  m1.scale = ({map}) => Math.max(1, Math.pow(1.45, map.zoom) / 64);\n  m1.map = map;\n  m1.icon = 'restaurant';\n  m1.color = '#DB4437';\n\n  type M2Data = {color: string};\n  const m2 = new Marker<M2Data>({\n    map,\n    position: {lat: 53.55, lng: 10},\n    scale: 2\n  });\n\n  m2.color = s => (s.data ? s.data.color : '#0F9D58');\n\n  const colors = ['#4285F4', '#DB4437', '#F4B400', '#0F9D58'];\n  let colorIdx = 0;\n\n  const intervalId = setInterval(() => {\n    m2.setData({color: colors[colorIdx]});\n    colorIdx = (colorIdx + 1) % colors.length;\n  }, 1000);\n\n  // the returned function will run before the running code is updated.\n  // This gives you an opportunity to clean up everything that has been added\n  // (don't worry aboutthe markers, they will be automatically removed from\n  // the map)\n  return () => {\n    clearInterval(intervalId);\n  };\n};\n"},"01.simple-marker.ts":{"title":"create marker and add it to the map","filename":"01.simple-marker.ts","source":"// title: create marker and add it to the map\nimport {Marker} from './lib/marker';\n\nexport default (map: google.maps.Map) => {\n  const m1 = new Marker();\n  m1.position = {lat: 53.555, lng: 10.001};\n  m1.map = map;\n\n  const m2 = new Marker({\n    map,\n    position: {lat: 53.55, lng: 10}\n  });\n};\n"},"02.update-position.ts":{"title":"specifying and updating position","filename":"02.update-position.ts","source":"// title: specifying and updating position\nimport {Marker} from './lib/marker';\n\nexport default (map: google.maps.Map) => {\n  const m1 = new Marker({map});\n\n  // at any point in time we can change the position\n  m1.position = {lat: 53.555, lng: 10.001};\n\n  map.setCenter(m1.position);\n};\n"},"03.pin-styling.ts":{"title":"simple marker customizations: color","filename":"03.pin-styling.ts","source":"// title: simple marker customizations: color\nimport {Marker} from './lib/marker';\n\nexport default (map: google.maps.Map) => {\n  const m1 = new Marker({map, position: {lat: 50, lng: 10}});\n  const m2 = new Marker({map, position: {lat: 50, lng: 11}});\n  const m3 = new Marker({map, position: {lat: 51, lng: 10}});\n  const m4 = new Marker({map, position: {lat: 51, lng: 11}});\n  const m5 = new Marker({map, position: {lat: 50.5, lng: 10.5}});\n\n  // the new color-attribute will update all color-properties of\n  // the markers with matching colors (all of these attributes can also be\n  // specified with the marker-options in the constructor)\n  m1.color = '#4285F4';\n  m2.color = '#DB4437';\n  m3.color = '#F4B400';\n  m4.color = '#0F9D58';\n\n  // alternatively, you can specify your own values for each of the\n  // properties, like so:\n  m5.backgroundColor = 'white';\n  m5.borderColor = 'black';\n  m5.glyphColor = 'salmon';\n\n  map.fitBounds(\n    new google.maps.LatLngBounds({lat: 49.5, lng: 9.5}, {lat: 51.5, lng: 11.5})\n  );\n};\n"},"04.pin-icons.ts":{"title":"simple marker customizations: icons","filename":"04.pin-icons.ts","source":"// title: simple marker customizations: icons\nimport {Marker} from './lib/marker';\nimport {MaterialIcons, MaterialIconsStyle} from './lib/icons';\n\nexport default (map: google.maps.Map) => {\n  // first we need to register the icon-provider, which is a function that knows how to create the kind of dom-element needed for an icon-set\n  Marker.registerIconProvider(\n    MaterialIcons({style: MaterialIconsStyle.FILLED})\n  );\n\n  const m1 = new Marker({\n    map,\n    position: {lat: 50, lng: 10},\n    scale: 1.5,\n    color: '#4285F4'\n  });\n  const m2 = new Marker({\n    map,\n    position: {lat: 50, lng: 11},\n    scale: 1.5,\n    color: '#DB4437'\n  });\n  const m3 = new Marker({\n    map,\n    position: {lat: 51, lng: 10},\n    scale: 1.5,\n    color: '#F4B400'\n  });\n  const m4 = new Marker({\n    map,\n    position: {lat: 51, lng: 11},\n    scale: 1.5,\n    color: '#0F9D58'\n  });\n\n  m1.icon = 'restaurant';\n  m2.icon = 'nightlife';\n  m3.icon = 'church';\n  m4.icon = 'home';\n\n  map.fitBounds(\n    new google.maps.LatLngBounds({lat: 49.5, lng: 9.5}, {lat: 51.5, lng: 11.5})\n  );\n};\n"}}
+{"00.default.ts":{"title":"00.default.ts","filename":"00.default.ts","source":"// Marker-API Example Playground\n//\n// Edit the code and hit CMD + Enter to execute it.\n//\n// Key bindings:\n//\n// <Cmd> + <Return>   compile typescript and execute\n// <Cmd> + <S>        save the code to the URL\n//\n\nimport {Marker} from './lib/marker';\nimport {MaterialIcons} from './lib/icons';\n\nexport default (map: google.maps.Map) => {\n  Marker.registerIconProvider(MaterialIcons());\n\n  const m1 = new Marker();\n  m1.position = {lat: 53.555, lng: 10.001};\n  m1.scale = ({map}) => Math.max(1, Math.pow(1.45, map.zoom) / 64);\n  m1.map = map;\n  m1.icon = 'restaurant';\n  m1.color = '#DB4437';\n\n  type M2Data = {color: string};\n  const m2 = new Marker<M2Data>({\n    map,\n    position: {lat: 53.55, lng: 10},\n    scale: 2\n  });\n\n  m2.color = s => (s.data ? s.data.color : '#0F9D58');\n\n  const colors = ['#4285F4', '#DB4437', '#F4B400', '#0F9D58'];\n  let colorIdx = 0;\n\n  const intervalId = setInterval(() => {\n    m2.data = {color: colors[colorIdx]};\n    colorIdx = (colorIdx + 1) % colors.length;\n  }, 1000);\n\n  // the returned function will run before the running code is updated.\n  // This gives you an opportunity to clean up everything that has been added\n  // (don't worry aboutthe markers, they will be automatically removed from\n  // the map)\n  return () => {\n    clearInterval(intervalId);\n  };\n};\n"},"01.simple-marker.ts":{"title":"create marker and add it to the map","filename":"01.simple-marker.ts","source":"// title: create marker and add it to the map\nimport {Marker} from './lib/marker';\n\nexport default (map: google.maps.Map) => {\n  const m1 = new Marker();\n  m1.position = {lat: 53.555, lng: 10.001};\n  m1.map = map;\n\n  const m2 = new Marker({\n    map,\n    position: {lat: 53.55, lng: 10}\n  });\n};\n"},"02.update-position.ts":{"title":"specifying and updating position","filename":"02.update-position.ts","source":"// title: specifying and updating position\nimport {Marker} from './lib/marker';\n\nexport default (map: google.maps.Map) => {\n  const m1 = new Marker({map});\n\n  // at any point in time we can change the position\n  m1.position = {lat: 53.555, lng: 10.001};\n\n  map.setCenter(m1.position);\n};\n"},"03.pin-styling.ts":{"title":"simple marker customizations: color","filename":"03.pin-styling.ts","source":"// title: simple marker customizations: color\nimport {Marker} from './lib/marker';\n\nexport default (map: google.maps.Map) => {\n  const m1 = new Marker({map, position: {lat: 50, lng: 10}});\n  const m2 = new Marker({map, position: {lat: 50, lng: 11}});\n  const m3 = new Marker({map, position: {lat: 51, lng: 10}});\n  const m4 = new Marker({map, position: {lat: 51, lng: 11}});\n  const m5 = new Marker({map, position: {lat: 50.5, lng: 10.5}});\n\n  // the new color-attribute will update all color-properties of\n  // the markers with matching colors (all of these attributes can also be\n  // specified with the marker-options in the constructor)\n  m1.color = '#4285F4';\n  m2.color = '#DB4437';\n  m3.color = '#F4B400';\n  m4.color = '#0F9D58';\n\n  // alternatively, you can specify your own values for each of the\n  // properties, like so:\n  m5.backgroundColor = 'white';\n  m5.borderColor = 'black';\n  m5.glyphColor = 'salmon';\n\n  map.fitBounds(\n    new google.maps.LatLngBounds({lat: 49.5, lng: 9.5}, {lat: 51.5, lng: 11.5})\n  );\n};\n"},"04.pin-icons.ts":{"title":"simple marker customizations: icons","filename":"04.pin-icons.ts","source":"// title: simple marker customizations: icons\nimport {Marker} from './lib/marker';\nimport {MaterialIcons, MaterialIconsStyle} from './lib/icons';\n\nexport default (map: google.maps.Map) => {\n  // first we need to register the icon-provider, which is a function that knows how to create the kind of dom-element needed for an icon-set\n  Marker.registerIconProvider(\n    MaterialIcons({style: MaterialIconsStyle.FILLED})\n  );\n\n  const m1 = new Marker({\n    map,\n    position: {lat: 50, lng: 10},\n    scale: 1.5,\n    color: '#4285F4'\n  });\n  const m2 = new Marker({\n    map,\n    position: {lat: 50, lng: 11},\n    scale: 1.5,\n    color: '#DB4437'\n  });\n  const m3 = new Marker({\n    map,\n    position: {lat: 51, lng: 10},\n    scale: 1.5,\n    color: '#F4B400'\n  });\n  const m4 = new Marker({\n    map,\n    position: {lat: 51, lng: 11},\n    scale: 1.5,\n    color: '#0F9D58'\n  });\n\n  m1.icon = 'restaurant';\n  m2.icon = 'nightlife';\n  m3.icon = 'church';\n  m4.icon = 'home';\n\n  map.fitBounds(\n    new google.maps.LatLngBounds({lat: 49.5, lng: 9.5}, {lat: 51.5, lng: 11.5})\n  );\n};\n"},"05.hover-styling.ts":{"title":"marker interactivity: hover","filename":"05.hover-styling.ts","source":"// title: marker interactivity: hover\nimport {Marker} from './lib/marker';\n\nexport default (map: google.maps.Map) => {\n  const marker = new Marker({\n    map,\n    position: {lat: 53.5, lng: 10}\n  });\n\n  marker.scale = ({marker}) => (marker.hovered ? 1.8 : 1.5);\n  marker.color = ({marker}) => (marker.hovered ? '#4285F4' : '#F4B400');\n};\n"},"06.click-events.ts":{"title":"marker interactivity: click events","filename":"06.click-events.ts","source":"// title: marker interactivity: click events\nimport {Marker} from './lib/marker';\n\nexport default (map: google.maps.Map) => {\n  const marker = new Marker({\n    map,\n    position: {lat: 53.5, lng: 10}\n  });\n\n  marker.addListener('click', () => {\n    alert('yep, that marker was clicked');\n  });\n};\n"},"07.mulitple-marker-single-select.ts":{"title":"multiple markers / single selection","filename":"07.mulitple-marker-single-select.ts","source":"// title: multiple markers / single selection\nimport {Marker} from './lib/marker';\n\nfunction rnd(min: number, max: number) {\n  return min + Math.random() * (max - min);\n}\n\nexport default (map: google.maps.Map) => {\n  const markers: Marker[] = [];\n  const bounds = new google.maps.LatLngBounds();\n\n  let selectedMarker: Marker | null = null;\n  const setSelected = (index: number) => {\n    if (selectedMarker !== null) {\n      selectedMarker.setData({selected: false});\n    }\n\n    const marker = markers[index];\n    marker.setData({selected: true});\n    selectedMarker = marker;\n  };\n\n  // create a couple of random markers\n  for (let i = 0; i < 10; i++) {\n    const position = {lat: rnd(53.5, 53.6), lng: rnd(9.9, 10.1)};\n    bounds.extend(position);\n\n    const marker = new Marker(\n      {\n        map,\n        position,\n        color: ({data}) => (data?.selected ? '#DB4437' : '#4285F4')\n      },\n      // initial user-data\n      {selected: false}\n    );\n\n    marker.addListener('click', () => {\n      console.log('marker clicked:', marker);\n      setSelected(i);\n    });\n\n    markers.push(marker as Marker);\n  }\n\n  map.fitBounds(bounds);\n};\n"}}

examples/lib/marker.d.ts

@@ -1,13 +1,12 @@
 /// <reference types="google.maps" />
 import type { IconProvider } from './icons';
-type TUserDataDefault = Record<string, unknown>;
 /**
  * The Marker class.
  * The optional type-parameter TUserData can be used to specify a type to
  * be used for the data specified in setData and available in the dynamic
  * attribute callbacks.
  */
-export declare class Marker<TUserData extends object = TUserDataDefault> {
+export declare class Marker<TUserData = unknown> {
     private static iconProviders;
     static registerIconProvider(provider: IconProvider, namespace?: string): void;
     position?: Attributes<TUserData>['position'];
@@ -22,7 +21,7 @@ export declare class Marker<TUserData extends object = TUserDataDefault> {
     borderColor?: Attributes<TUserData>['borderColor'];
     glyphColor?: Attributes<TUserData>['glyphColor'];
     icon?: Attributes<TUserData>['icon'];
-    private data_;
+    private data_?;
     private markerState_;
     private mapState_;
     readonly attributes_: Partial<StaticAttributes>;
@@ -41,32 +40,41 @@ export declare class Marker<TUserData extends object = TUserDataDefault> {
      * @param data
      */
     constructor(options?: MarkerOptions<TUserData>, data?: TUserData);
-    /**
-     * Sets the data for this marker and triggers an update.
-     * @param data
-     */
-    setData(data: TUserData): void;
     /**
      * Adds an event-listener to this marker. The internal events (click and
      * dragging events) are attached to the marker instance using the Google Maps
      * event system, while any dom-events will be added to the marker-element
      * itself.
+     *
+     * FIXME: normalize event-handler-parameters
+     * FIXME: extend the typings to be explicit about the callback-parameters
+     *
      * @param eventName 'click', 'dragstart', 'dragend', 'drag' or any DOM event-name.
      * @param handler
      */
-    addListener(eventName: string, handler: (ev: google.maps.MapMouseEvent) => void): google.maps.MapsEventListener;
+    addListener(eventName: string, handler: (ev: google.maps.MapMouseEvent | Event) => void): google.maps.MapsEventListener;
     /**
      * The map property is a proxy for this.markerView_.map, setting the map
      * will also retrieve the view-state from the map and update the marker.
      */
     get map(): google.maps.Map | null;
     set map(map: google.maps.Map | null);
+    /**
+     * Sets the data for this marker and triggers an update.
+     * @param data
+     */
+    setData(data: TUserData): void;
     /**
      * Updates the colors for the embedded pin-view based on the different
      * color attributes.
      * @param attributes
      */
-    private updatePinViewColors;
+    private updateColors;
+    enableEvents(): void;
+    disableEvents(): void;
+    /**
+     * Binds the required dom-events to the marker-instance.
+     */
     private bindMarkerEvents;
     /**
      * Handles the bounds_changed event for the map to update our internal state.
@@ -110,7 +118,7 @@ export interface StaticAttributes {
 }
 export type AttributeKey = keyof StaticAttributes;
 export type DynamicAttributeValue<TUserData, TAttr> = (state: {
-    data: TUserData | null;
+    data: TUserData;
 } & {
     map: MapState;
     marker: MarkerState;
@@ -137,4 +145,3 @@ export type MarkerState = {
     hovered: boolean;
     visible: boolean;
 };
-export {};