diff --git a/packages/mdc-ripple/README.md b/packages/mdc-ripple/README.md index 0f5e66512bf..72d1562d2f1 100644 --- a/packages/mdc-ripple/README.md +++ b/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. diff --git a/packages/mdc-ripple/index.js b/packages/mdc-ripple/index.js index ada56fc38ce..4d7ac73d829 100644 --- a/packages/mdc-ripple/index.js +++ b/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),