Address feedback from PR

src/dom/get-visible-y-from-root.ts → src/dom/get-viewport-y.ts

@@ -1,19 +1,38 @@
 import { dom } from '../';
 import { domVectorf } from './dom-vectorf';
 
+/**
+ * Determine if the given element is fixed.
+ */
 function isFixed(element: HTMLElement) {
   return dom.getStyle(element).position === 'fixed';
 }
 
-function getTransformedOffset(candidateElement: HTMLElement): number {
+/**
+ * Factor in the transform of the given element when determining its offseTop
+ */
+function getTransformedOffsetTop(candidateElement: HTMLElement): number {
   return candidateElement.offsetTop +
       domVectorf.fromElementTransform(candidateElement).y;
 }
 
-function getVisibleDistanceFromRoot(
-    element: HTMLElement,
-    getOffsetFn: (e: HTMLElement) => number
-): number {
+/**
+ * Returns the visible distance between the top of the given element and the
+ * top of the viewport.
+ *
+ * Useful for specific scroll-based effects and in-view checks that cannot
+ * be easily expressed via a configuration.
+ *
+ * ```
+ * function getEffectPercent() {
+ *    const start = getSomeHeaderHeight();
+ *    const end = start + getViewportHeight() - getSomeFooterHeight();
+ *    const distanceFromRoot = getViewportY(this.el);
+ *    return mathf.inverseLerp(-1 * start, -1 * end, -1 * distanceFromRoot);
+ * }
+ * ```
+ */
+export function getViewportY(element: HTMLElement): number {
   // Short circuit for fixed elements.
   if (isFixed(element)) {
     return element.offsetTop;
@@ -28,18 +47,13 @@ function getVisibleDistanceFromRoot(
       return y + candidateElement.offsetTop;
     } else {
       // Factor in the offset and the scroll
-      y += getOffsetFn(candidateElement) - candidateElement.scrollTop;
+      y +=
+          getTransformedOffsetTop(candidateElement) -
+          candidateElement.scrollTop;
     }
     candidateElement = <HTMLElement>candidateElement.offsetParent;
   }
 
-  return getOffsetFn(element) + y - dom.getScrollElement().scrollTop;
-}
-
-/**
- * Returns the visible distance between the top of the given element and the
- * top of the viewport.
- */
-export function getVisibleYFromRoot(element: HTMLElement) {
-  return getVisibleDistanceFromRoot(element, getTransformedOffset);
+  return getTransformedOffsetTop(element) + y -
+      dom.getScrollElement().scrollTop;
 }