Add hidden overflow margin to overlays (uber#748)

modules/overlays/src/html-overlay.tsx

@@ -6,13 +6,24 @@ const styles = {
     height: '100%',
     position: 'absolute',
     pointerEvents: 'none',
+    overflow: 'hidden',
   },
 };
 
-export default class HtmlOverlay extends React.Component<
-  { viewport?: Record<string, any>; zIndex?: number; children?: React.ReactNode },
-  any
-> {
+interface Props {
+  viewport?: Record<string, any>;
+  zIndex?: number;
+  children?: React.ReactNode;
+  // Overlay items abruptly disappear when their anchor point passes the edge of the map, which is
+  // visible to the user. The overflowMargin prop is used to effectively create a hidden buffer
+  // zone that extends from all sides of the map while leaving the visible edge of the map
+  // unchanged. With this, overlay items can move into the buffer zone and disappear only when
+  // their anchor passes the edge of the buffer zone. This produces a perceived effect of overlay
+  // items being rendered as part of the map, instead of separate entities tacked on to the map.
+  overflowMargin?: number;
+}
+
+export default class HtmlOverlay extends React.Component<Props> {
   // Override this to provide your items
   getItems(): Array<any> {
     const { children } = this.props;
@@ -29,8 +40,14 @@ export default class HtmlOverlay extends React.Component<
   }
 
   inView([x, y]: number[]): boolean {
-    const { width, height } = this.props.viewport;
-    return !(x < 0 || y < 0 || x > width || y > height);
+    const { viewport, overflowMargin = 0 } = this.props;
+    const { width, height } = viewport;
+    return !(
+      x < -overflowMargin ||
+      y < -overflowMargin ||
+      x > width + overflowMargin ||
+      y > height + overflowMargin
+    );
   }
 
   scaleWithZoom(n: number) {
@@ -71,5 +88,5 @@ export default class HtmlOverlay extends React.Component<
 }
 
 // This is needed for Deck.gl 8.0+
-//@ts-ignore
+// @ts-ignore
 HtmlOverlay.deckGLViewProps = true;