feat(ripple): export util from @material/ripple (#751)

Resolves #253: The docs recommend using certain functions from util when implementing an adapter for the ripple foundation. Export util from index.js so this is possible.

Author: Kerrick

packages/mdc-ripple/README.md

@@ -33,6 +33,7 @@ path: /catalog/ripples/
     - [Specifying known element dimensions](#specifying-known-element-dimensions)
   - [Caveat: Safari](#caveat-safari)
   - [Caveat: Theme Custom Variables](#caveat-theme-custom-variables)
+  - [The util API](#the-util-api)
 
 MDC Ripple provides the Javascript and CSS required to provide components (or any element at all) with a material "ink ripple" interaction effect. It is designed to be efficient, uninvasive, and usable without adding any extra DOM to your elements.
 
@@ -125,13 +126,13 @@ First import the ripple JS
 ##### ES2015
 
 ```javascript
-import {MDCRipple, MDCRippleFoundation} from '@material/ripple';
+import {MDCRipple, MDCRippleFoundation, util} from '@material/ripple';
 ```
 
 ##### CommonJS
 
 ```javascript
-const {MDCRipple, MDCRippleFoundation} = require('@material/ripple');
+const {MDCRipple, MDCRippleFoundation, util} = require('@material/ripple');
 ```
 
 ##### AMD
@@ -140,6 +141,7 @@ const {MDCRipple, MDCRippleFoundation} = require('@material/ripple');
 require('path/to/@material/ripple', function(mdcRipple) {
   const MDCRipple = mdcRipple.MDCRipple;
   const MDCRippleFoundation = mdcRipple.MDCRippleFoundation;
+  const util = mdcRipple.util;
 });
 ```
 
@@ -148,6 +150,7 @@ require('path/to/@material/ripple', function(mdcRipple) {
 ```javascript
 const MDCRipple = mdc.ripple.MDCRipple;
 const MDCRippleFoundation = mdc.ripple.MDCRippleFoundation;
+const util = mdc.ripple.util;
 ```
 
 Then, simply initialize the ripple with the correct DOM element.
@@ -408,3 +411,23 @@ background: color(var(--mdc-theme-primary) a(6%));
 But as far as we know, no browsers yet support it. We have added a `@supports` clause into our code
 to make sure that it can be used as soon as browsers adopt it, but for now this means that _changes
 to your theme via a custom variable will not propagate to ripples._ We don't see this being a gigantic issue as we envision most users configuring one theme via sass. For places where you do need this, special treatment will have to be given.
+
+### The util API
+
+External frameworks and libraries can use the following utility methods when integrating a component.
+
+#### util.supportsCssVariables(windowObj) => Boolean
+
+Determine whether the current browser supports CSS variables (custom properties).
+
+#### util.applyPassive(globalObj = window, forceRefresh = false) => object
+
+Determine whether the current browser supports passive event listeners, and if so, use them.
+
+#### getMatchesProperty(HTMLElementPrototype) => Function
+
+Choose the correct matches property to use on the current browser.
+
+#### getNormalizedEventCoords(ev, pageOffset, clientRect) => object
+
+Determines X/Y coordinates of an event normalized for touch events and ripples.

packages/mdc-ripple/index.js

@@ -16,9 +16,10 @@
 
 import {MDCComponent} from '@material/base';
 import MDCRippleFoundation from './foundation';
-import {applyPassive, supportsCssVariables, getMatchesProperty} from './util';
+import * as util from './util';
 
 export {MDCRippleFoundation};
+export {util};
 
 export class MDCRipple extends MDCComponent {
   static attachTo(root, {isUnbounded = undefined} = {}) {
@@ -31,19 +32,19 @@ export class MDCRipple extends MDCComponent {
   }
 
   static createAdapter(instance) {
-    const MATCHES = getMatchesProperty(HTMLElement.prototype);
+    const MATCHES = util.getMatchesProperty(HTMLElement.prototype);
 
     return {
-      browserSupportsCssVars: () => supportsCssVariables(window),
+      browserSupportsCssVars: () => util.supportsCssVariables(window),
       isUnbounded: () => instance.unbounded,
       isSurfaceActive: () => instance.root_[MATCHES](':active'),
       isSurfaceDisabled: () => instance.disabled,
       addClass: (className) => instance.root_.classList.add(className),
       removeClass: (className) => instance.root_.classList.remove(className),
       registerInteractionHandler: (evtType, handler) =>
-          instance.root_.addEventListener(evtType, handler, applyPassive()),
+          instance.root_.addEventListener(evtType, handler, util.applyPassive()),
       deregisterInteractionHandler: (evtType, handler) =>
-          instance.root_.removeEventListener(evtType, handler, applyPassive()),
+          instance.root_.removeEventListener(evtType, handler, util.applyPassive()),
       registerResizeHandler: (handler) => window.addEventListener('resize', handler),
       deregisterResizeHandler: (handler) => window.removeEventListener('resize', handler),
       updateCssVariable: (varName, value) => instance.root_.style.setProperty(varName, value),