@bostonuniversity/bulib-wc/src/_helpers/browsers.stories.mdx

collection of web components and styles used at Boston University Libraries

import { Story, Preview, Meta, Props, html, withKnobs, withWebComponentsKnobs } from '@open-wc/demoing-storybook';

<Meta title="JS Helpers|Browser Compatibility"/>

# Browser Compatibility Helper

There are minor issues with some legacy browsers that do not support Web Components. 

We want to have some visibility into **how often** this happens, and we always want to provide users 
  with a **fallback experience** (_graceful degradation_ and _progressive enhancement_), that allows 
  them to fulfill the main goal of that page/site. 


## Importing the Helper

Add the following `<script>` to the sitewide javascript to add them to the global scope 
  and enable their use throughout the site.

```html
<script type="text/javascript" src="https://unpkg.com/bulib-wc@0.1.46/dist/helpers.js" defer></script>
```

## Usages 

_AFTER_ importing the helper...

### Check to See If Web Components Are Supported By the Client's Browser 

Adding the following call (normally right below the import, sitewide), will 
  inform the console and google analytics if the browser was able to load the 
  web components for that page visit 

```html
<script type="text/javascript">
  doesBrowserSupportWebComponents(true);
</script>
```

_NOTE: This helper reports the results to analytics behind the scenes with the assistance of `google_analytix.js` helper._

### Safely Replace the Fallback Elements If Web Components Are Supported

```html
<!-- import helper from the CDN -->

<!-- set the selected elements to replace and the web component to (potentially) replace them with -->
<script type="text/javascript">
  let tagname_for_web_component = "bulib-component";
  let list_of_elements_to_replace = [ 
    document.getElementById("an-id-selector"), 
    document.querySelector("div.a-class-name > span"), 
    document.querySelector("div.another-class > h3")
  ];
  loadWebComponentsInto(tagname_for_web_component, list_of_elements_to_replace);]
</script>
```