[feature] add mediaCapabilities hook (#30)

* add mediaCapabilities hook

* update README.md with useMediaCapabilities hook

* cleanup mediaCapabilities test

* remove usage of useState and useEffect in media-capabilities

* simplify things

* add initialMediaCapabilities

* add a better example in readme for useMediaCapabilities

* better copy to align style of writing with writings from @mlampedx

Co-authored-by: Addy Osmani <addyosmani@gmail.com>

Author: wingleung

README.md

@@ -8,6 +8,7 @@ This is a suite of [React Hooks](https://reactjs.org/docs/hooks-overview.html) a
 * [Data Saver preferences](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/saveData)
 * [Device memory](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/deviceMemory)
 * [Logical CPU cores](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorConcurrentHardware/hardwareConcurrency)
+* [Media Capabilities API](https://developer.mozilla.org/en-US/docs/Web/API/Media_Capabilities_API)
 
 It can be used to add patterns for adaptive resource loading, data-fetching, code-splitting and capability toggling.
 
@@ -28,6 +29,7 @@ import { useNetworkStatus } from 'react-adaptive-hooks/network';
 import { useSaveData } from 'react-adaptive-hooks/save-data';
 import { useHardwareConcurrency } from 'react-adaptive-hooks/hardware-concurrency';
 import { useMemoryStatus } from 'react-adaptive-hooks/memory';
+import { useMediaCapabilities } from 'react-adaptive-hooks/media-capabilities';
 ```
 
 and then use them in your components. Examples for each hook and utility can be found below:
@@ -156,6 +158,54 @@ const initialMemoryStatus = { deviceMemory: 4 };
 const { deviceMemory } = useMemoryStatus(initialMemoryStatus);
 ```
 
+### Media Capabilities
+
+`useMediaCapabilities` utility for adapting based on the user's device media capabilities.
+
+**Use case:** this hook can be used to check if we can play a certain content type. For example, Safari does not support WebM so we want to fallback to MP4 but if Safari at some point does support WebM it will automatically load WebM videos.
+
+```js
+import React from 'react';
+
+import { useMediaCapabilities } from 'react-adaptive-hooks/media-capabilities';
+
+const webmMediaConfig = {
+  type : 'file', // 'record', 'transmission', or 'media-source'
+  video : {
+    contentType : 'video/webm;codecs=vp8', // valid content type
+    width : 800,     // width of the video
+    height : 600,    // height of the video
+    bitrate : 10000, // number of bits used to encode 1s of video
+    framerate : 30   // number of frames making up that 1s.
+  }
+};
+
+const initialDecodingInfo = { showWarning: true }
+
+const MyComponent = ({ videoSources }) => {
+  const { mediaCapabilities } = useMediaCapabilities(webmMediaConfig, initialDecodingInfo);
+
+  return (
+    <div>
+      {
+        mediaCapabilities.supported
+          ? <video src={videoSources.webm} controls>...</video>
+          : <video src={videoSources.mp4}  controls>...</video>
+      }
+      {
+        mediaCapabilities.showWarning &&
+          <div class="muted">
+            Defaulted to mp4.
+            Couldn't test webm support, either the media capabilities api is unavailable or no media configuration was given.
+          </div>
+      }
+    </div>
+  );
+};
+```
+
+This hook accepts a [media configuration](https://developer.mozilla.org/en-US/docs/Web/API/MediaConfiguration) object argument and an optional `initialMediaCapabilities` object argument, which can be used to provide a `mediaCapabilities` state value when the user's browser does not support the relevant [Media Capabilities API](https://developer.mozilla.org/en-US/docs/Web/API/Media_Capabilities_API) or no media configuration was given.
+
 ### Adaptive Code-loading & Code-splitting
 
 #### Code-loading
@@ -258,6 +308,8 @@ export default App;
 
 * [Device Memory API](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/deviceMemory) is available in [Chrome 63+, Opera 50+, Chrome for Android 76+, Opera for Android 46+](https://caniuse.com/#search=deviceMemory)
 
+* [Media Capabilities API](https://developer.mozilla.org/en-US/docs/Web/API/Media_Capabilities_API) is available in [Chrome 63+, Firefox 63+, Opera 55+, Chrome for Android 78+, Firefox for Android 68+](https://caniuse.com/#search=media%20capabilities)
+
 ## Demos
 
 ### Network

index.js

@@ -2,3 +2,4 @@ export { useNetworkStatus } from './network';
 export { useSaveData } from './save-data';
 export { useMemoryStatus } from './memory';
 export { useHardwareConcurrency } from './hardware-concurrency';
+export { useMediaCapabilities } from './media-capabilities'

media-capabilities/index.js

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2019 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const useMediaCapabilities = (mediaConfig, initialMediaCapabilities = {}) => {
+    let mediaCapabilities = {
+        supported: typeof window !== 'undefined' && 'mediaCapabilities' in navigator,
+        hasMediaConfig: !!mediaConfig
+    }
+
+    mediaCapabilities = (mediaCapabilities.supported && mediaCapabilities.hasMediaConfig) ?
+        navigator.mediaCapabilities.decodingInfo(mediaConfig) :
+        {
+            ...mediaCapabilities,
+            ...initialMediaCapabilities
+        }
+
+    return { mediaCapabilities };
+};
+
+export {
+    useMediaCapabilities
+};

media-capabilities/media-capabilities.test.js

@@ -0,0 +1,95 @@
+/*
+ * Copyright 2019 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the 'License');
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an 'AS IS' BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { renderHook } from '@testing-library/react-hooks';
+
+import { useMediaCapabilities } from './';
+
+const mediaConfig = {
+    type: 'file',
+    audio: {
+        contentType: 'audio/mp3',
+        channels: 2,
+        bitrate: 132700,
+        samplerate: 5200
+    }
+};
+
+const mediaCapabilitiesMapper = {
+    'audio/mp3': {
+        powerEfficient: true,
+        smooth: true,
+        supported: true
+    }
+}
+
+describe('useMediaCapabilities', () => {
+    test('should return supported flag on unsupported platforms', () => {
+        const { result } = renderHook(() => useMediaCapabilities(mediaConfig));
+
+        expect(result.current.mediaCapabilities).toEqual({ hasMediaConfig: true, supported: false });
+    });
+
+    test('should return supported and hasMediaConfig flags on unsupported platforms and no config given', () => {
+        const { result } = renderHook(() => useMediaCapabilities());
+        
+        expect(result.current.mediaCapabilities).toEqual({ hasMediaConfig: false, supported: false });
+    });
+
+    test('should return initialMediaCapabilities for unsupported', () => {
+        const initialMediaCapabilities = {
+            supported: true,
+            smooth: false,
+            powerEfficient: true
+        };
+
+        const { result } = renderHook(() => useMediaCapabilities(mediaConfig, initialMediaCapabilities));
+
+        expect(result.current.mediaCapabilities.supported).toBe(true);
+        expect(result.current.mediaCapabilities.smooth).toEqual(false);
+        expect(result.current.mediaCapabilities.powerEfficient).toEqual(true);
+    });
+
+    test('should return hasMediaConfig flag when no config given', () => {
+        Object.defineProperty(window.navigator, 'mediaCapabilities', {
+            value: true,
+            configurable: true,
+            writable: true
+        });
+        
+        const { result } = renderHook(() => useMediaCapabilities());
+        
+        expect(result.current.mediaCapabilities).toEqual({ hasMediaConfig: false, supported: true });
+    });
+    
+    test('should return MediaDecodingConfiguration for given media configuration', () => {
+        Object.defineProperty(window.navigator, 'mediaCapabilities', {
+            value: {
+                decodingInfo: (mediaConfig) => mediaCapabilitiesMapper[mediaConfig.audio.contentType]
+            },
+            configurable: true,
+            writable: true
+        });
+
+        const { result } = renderHook(() => useMediaCapabilities(mediaConfig));
+
+        expect(result.current.mediaCapabilities).toEqual({
+            powerEfficient: true,
+            smooth: true,
+            supported: true
+        });
+    });
+});