@cfpb/cfpb-design-system 5.1.0 → 5.3.0

package/src/elements/{cfpb-list → cfpb-listbox}/index.js

@@ -1,10 +1,10 @@
 import { LitElement, html, css, unsafeCSS } from 'lit';
 import { ref, createRef } from 'lit/directives/ref.js';
-import styles from './cfpb-list.component.scss?inline';
-import { CfpbListItem } from '../cfpb-list-item';
+import styles from './styles.component.scss?inline';
+import { CfpbListboxItem } from '../cfpb-listbox-item';
 import { parseChildData } from '../cfpb-utilities/parse-child-data';
 
-export class CfpbList extends LitElement {
+export class CfpbListbox extends LitElement {
   static styles = css`
     ${unsafeCSS(styles)}
   `;
@@ -84,7 +84,7 @@ export class CfpbList extends LitElement {
 
     let firstChecked = null;
     itemsArray.forEach((data) => {
-      const item = document.createElement('cfpb-list-item');
+      const item = document.createElement('cfpb-listbox-item');
       item.textContent = data.value ?? '';
       if ('disabled' in data) item.disabled = data.disabled;
       if ('hidden' in data) item.hidden = data.hidden;
@@ -109,7 +109,7 @@ export class CfpbList extends LitElement {
   // -------------------------
   #syncItems() {
     // Collect items.
-    this.#items = [...this.querySelectorAll('cfpb-list-item')];
+    this.#items = [...this.querySelectorAll('cfpb-listbox-item')];
 
     // Ensure each item has a type.
     this.#items.forEach((item) => {
@@ -187,7 +187,7 @@ export class CfpbList extends LitElement {
   #applyTypeToItems() {
     if (!['plain', 'check', 'checkbox'].includes(this.type)) {
       // eslint-disable-next-line no-console
-      console.warn(`<cfpb-list>: invalid type "${this.type}".`);
+      console.warn(`<cfpb-listbox>: invalid type "${this.type}".`);
       return;
     }
     this.#items.forEach((item) => (item.type = this.type));
@@ -372,9 +372,10 @@ export class CfpbList extends LitElement {
   }
 
   static init() {
-    CfpbListItem.init();
-    if (!window.customElements.get('cfpb-list')) {
-      window.customElements.define('cfpb-list', CfpbList);
+    CfpbListboxItem.init();
+
+    if (!window.customElements.get('cfpb-listbox')) {
+      window.customElements.define('cfpb-listbox', CfpbListbox);
     }
   }
 }

package/src/elements/{cfpb-list → cfpb-listbox}/index.spec.js

@@ -1,15 +1,15 @@
 import { jest } from '@jest/globals';
-import { CfpbList } from './index';
+import { CfpbListbox } from './index';
 
 beforeAll(() => {
-  CfpbList.init();
+  CfpbListbox.init();
 });
 
-describe('<cfpb-list> tests', () => {
+describe('<cfpb-listbox> tests', () => {
   let list;
 
   beforeEach(() => {
-    list = document.createElement('cfpb-list');
+    list = document.createElement('cfpb-listbox');
     document.body.appendChild(list);
   });
 
@@ -123,7 +123,7 @@ describe('<cfpb-list> tests', () => {
 
     const container = list.shadowRoot.querySelector('div');
     container.focus();
-    expect(document.activeElement.tagName).toBe('CFPB-LIST');
+    expect(document.activeElement.tagName).toBe('CFPB-LISTBOX');
 
     // ArrowDown → first visible
     container.dispatchEvent(
@@ -141,7 +141,7 @@ describe('<cfpb-list> tests', () => {
     container.dispatchEvent(
       new KeyboardEvent('keydown', { key: 'ArrowUp', bubbles: true }),
     );
-    expect(document.activeElement.tagName).toBe('CFPB-LIST');
+    expect(document.activeElement.tagName).toBe('CFPB-LISTBOX');
   });
 
   test('showAllItems unhides all items', async () => {
@@ -173,21 +173,21 @@ describe('<cfpb-list> tests', () => {
     list.childData = JSON.stringify([{ value: 'A' }, { value: 'B' }]);
     await list.updateComplete;
     list.focusItemAt(-1);
-    expect(document.activeElement.tagName).toBe('CFPB-LIST');
+    expect(document.activeElement.tagName).toBe('CFPB-LISTBOX');
   });
 
   test('focusItemAt(null) focuses the container', async () => {
     list.childData = JSON.stringify([{ value: 'A' }]);
     await list.updateComplete;
     list.focusItemAt(null);
-    expect(document.activeElement.tagName).toBe('CFPB-LIST');
+    expect(document.activeElement.tagName).toBe('CFPB-LISTBOX');
   });
 
   test('focusItemAt(undefined) focuses the container', async () => {
     list.childData = JSON.stringify([{ value: 'A' }]);
     await list.updateComplete;
     list.focusItemAt(undefined);
-    expect(document.activeElement.tagName).toBe('CFPB-LIST');
+    expect(document.activeElement.tagName).toBe('CFPB-LISTBOX');
   });
 
   test('ArrowDown from container focuses first visible item', async () => {

package/src/elements/{cfpb-list/cfpb-list.component.scss → cfpb-listbox/styles.component.scss}

@@ -1,9 +1,5 @@
-@use 'sass:math';
-@use '@cfpb/cfpb-design-system/src/elements/abstracts' as *;
-@use '@cfpb/cfpb-design-system/src/components/cfpb-icons/icon';
-
 :host {
-  ::slotted(cfpb-list-item) {
+  ::slotted(cfpb-listbox-item) {
     position: relative;
     margin-top: 1px;
 

package/src/elements/{cfpb-list-item → cfpb-listbox-item}/index.js

@@ -1,13 +1,13 @@
 import { LitElement, html, css, unsafeCSS } from 'lit';
-import styles from './cfpb-list-item.component.scss?inline';
+import styles from './styles.component.scss?inline';
 import { ref, createRef } from 'lit/directives/ref.js';
 import { CfpbCheckboxIcon } from '../cfpb-checkbox-icon';
 
 /**
- * @element cfpb-list-item.
+ * @element cfpb-listbox-item.
  * @slot - The text for the list item.
  */
-export class CfpbListItem extends LitElement {
+export class CfpbListboxItem extends LitElement {
   static styles = css`
     ${unsafeCSS(styles)}
   `;
@@ -208,8 +208,8 @@ export class CfpbListItem extends LitElement {
   static init() {
     CfpbCheckboxIcon.init();
 
-    if (!window.customElements.get('cfpb-list-item')) {
-      window.customElements.define('cfpb-list-item', CfpbListItem);
+    if (!window.customElements.get('cfpb-listbox-item')) {
+      window.customElements.define('cfpb-listbox-item', CfpbListboxItem);
     }
   }
 }

package/src/elements/{cfpb-list-item/cfpb-list-item.component.scss → cfpb-listbox-item/styles.component.scss}

@@ -1,5 +1,6 @@
-@use 'sass:math';
 @use '@cfpb/cfpb-design-system/src/elements/abstracts' as *;
+@use '@cfpb/cfpb-design-system/src/components/cfpb-icons/icons-lib' as *;
+@use '../../utilities/functions' as *;
 
 :host {
   // Theme variables.
@@ -17,7 +18,7 @@
     display: inline-grid;
 
     // 30px is width of checkbox/radio button plus the needed padding.
-    grid-template-columns: math.div(30px, $base-font-size-px) + em auto;
+    grid-template-columns: rem-from-px(30px) auto;
     vertical-align: top;
 
     // Wrap long words in narrow form fields to prevent clipping
@@ -48,7 +49,7 @@
 
 :host([checked]) {
   .checkbox::before {
-    --cfpb-background-icon-svg: 'approved';
+    background-image: $cfpb-background-icon-svg-approved;
 
     background-size: auto $cf-icon-height;
     background-repeat: no-repeat;

package/src/elements/cfpb-pagination/index.js

@@ -1,8 +1,6 @@
 import { LitElement, html, css, unsafeCSS } from 'lit';
-import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-import styles from './cfpb-pagination.component.scss?inline';
-import leftIcon from '../../components/cfpb-icons/icons/left.svg?raw';
-import rightIcon from '../../components/cfpb-icons/icons/right.svg?raw';
+import styles from './styles.component.scss?inline';
+import { CfpbIcon } from '../cfpb-icon';
 import { I18nService, MediaQueryService } from '../cfpb-utilities/';
 
 /**
@@ -154,7 +152,7 @@ export class CfpbPagination extends LitElement {
           ?disabled=${this.isAtMin}
           @click=${() => this.#goto(this.currentPage - 1)}
         >
-          ${unsafeSVG(leftIcon)} ${trans('next')}
+          <cfpb-icon name="left" color="white"></cfpb-icon> ${trans('next')}
         </cfpb-button>
 
         <form
@@ -194,13 +192,15 @@ export class CfpbPagination extends LitElement {
           ?disabled=${this.isAtMax}
           @click=${() => this.#goto(this.currentPage + 1)}
         >
-          ${trans('previous')} ${unsafeSVG(rightIcon)}
+          ${trans('previous')}
+          <cfpb-icon name="right" color="white"></cfpb-icon>
         </cfpb-button>
       </nav>
     `;
   }
 
   static init() {
+    CfpbIcon.init();
     I18nService.init();
 
     window.customElements.get('cfpb-pagination') ||

package/src/elements/cfpb-pagination/{cfpb-pagination.component.scss → styles.component.scss}

@@ -1,7 +1,7 @@
-@use 'sass:math';
 @use '@cfpb/cfpb-design-system/src/elements/abstracts' as *;
 @use '@cfpb/cfpb-design-system/src/utilities' as *;
 @use '@cfpb/cfpb-design-system/src/components/cfpb-icons/icon' as *;
+@use '../../utilities/functions' as *;
 
 :host {
   width: 100%;
@@ -12,17 +12,17 @@
     grid-template-areas:
       'pag-btn-prev . pag-btn-next'
       'pag-form pag-form pag-form';
-    row-gap: math.div(15px, $base-font-size-px) + rem;
+    row-gap: rem-from-px(15px);
 
     &__form {
       grid-area: pag-form;
       display: flex;
       flex-flow: wrap;
       place-content: center;
-      gap: math.div(10px, $base-font-size-px) + rem;
+      gap: rem-from-px(10px);
 
-      padding: math.div(5px, $base-font-size-px) + rem;
-      border-radius: math.div(4px, $base-font-size-px) + rem;
+      padding: rem-from-px(5px);
+      border-radius: rem-from-px(4px);
       background: var(--gray-5);
       color: var(--gray);
     }
@@ -30,7 +30,7 @@
     &__current-page {
       // 45px is a magic number to provide enough room for three digits
       // and the number spinners for type="number" inputs on desktop
-      width: math.div(45px, $base-font-size-px) + rem;
+      width: rem-from-px(45px);
 
       font-weight: 500;
       text-align: right;

package/src/elements/cfpb-select/index.js

@@ -1,14 +1,12 @@
 import { html, LitElement, css, unsafeCSS, nothing } from 'lit';
 import { ref, createRef } from 'lit/directives/ref.js';
-import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-import styles from './cfpb-select.component.scss?inline';
-import expandIcon from '../../components/cfpb-icons/icons/down.svg?raw';
-import collapseIcon from '../../components/cfpb-icons/icons/up.svg?raw';
+import styles from './styles.component.scss?inline';
+import { CfpbIcon } from '../cfpb-icon';
 import { CfpbFormSearchInput } from '../cfpb-form-search-input';
 import { SearchService } from '../cfpb-utilities/search-service.js';
 import { MaxHeightTransition } from '../../utilities/transition/max-height-transition';
 import { FlyoutMenu } from '../../utilities/behavior/flyout-menu';
-import { CfpbList } from '../cfpb-list';
+import { CfpbListbox } from '../cfpb-listbox';
 import { CfpbTagGroup } from '../cfpb-tag-group';
 
 import { SingleSelectEventProxy } from './single-select-event-proxy.js';
@@ -312,11 +310,11 @@ export class CfpbSelect extends LitElement {
           @click=${this.#onClick}
         >
           <span class="o-select__cue-open" role="img" aria-label="Show">
-            ${unsafeSVG(expandIcon)}
+            <cfpb-icon name="down"></cfpb-icon>
             <span class="u-visually-hidden">Show</span>
           </span>
           <span class="o-select__cue-close" role="img" aria-label="Hide">
-            ${unsafeSVG(collapseIcon)}
+            <cfpb-icon name="up"></cfpb-icon>
             <span class="u-visually-hidden">Hide</span>
           </span>
         </button>
@@ -325,7 +323,7 @@ export class CfpbSelect extends LitElement {
           data-js-hook="behavior_flyout-menu_content"
           ${ref(this.#contentDom)}
         >
-          <cfpb-list
+          <cfpb-listbox
             tabindex=${this.#noResults ? '-1' : '0'}
             @item-click=${this.#onItemClick}
             ?multiple=${this.multiple}
@@ -336,7 +334,7 @@ export class CfpbSelect extends LitElement {
               : 'Choose an item…'}
             ${ref(this.#list)}
           >
-          </cfpb-list>
+          </cfpb-listbox>
           <div class=${this.#noResults ? 'no-results' : 'u-hidden'}>
             No results found
           </div>
@@ -371,8 +369,9 @@ export class CfpbSelect extends LitElement {
   }
 
   static init() {
+    CfpbIcon.init();
     CfpbFormSearchInput.init();
-    CfpbList.init();
+    CfpbListbox.init();
     CfpbTagGroup.init();
 
     window.customElements.get('cfpb-select') ||

package/src/elements/cfpb-select/multiple-select-event-proxy.js

@@ -11,7 +11,7 @@ export class MultipleSelectEventProxy {
   }
 
   onBlur() {
-    // In multiselect, blur happens when inside the list, so we ignore any
+    // In multiselect, blur happens when inside the listbox, so we ignore any
     // blur actions.
   }
 
@@ -72,7 +72,7 @@ export class MultipleSelectEventProxy {
           host.isExpanded = !host.isExpanded;
           break;
       }
-    } else if (focused === 'CFPB-LIST-ITEM') {
+    } else if (focused === 'CFPB-LISTBOX-ITEM') {
       switch (evt.key) {
         case 'Tab':
           if (evt.shiftKey) {

package/src/elements/cfpb-select/single-select-event-proxy.js

@@ -42,7 +42,7 @@ export class SingleSelectEventProxy {
         case 'ArrowDown':
           evt.preventDefault();
           host.isExpanded = true;
-          this.list.querySelector('cfpb-list-item')?.focus();
+          this.list.querySelector('cfpb-listbox-item')?.focus();
           break;
       }
     }

package/src/elements/cfpb-select/{cfpb-select.component.scss → styles.component.scss}

@@ -1,9 +1,8 @@
-@use 'sass:math';
-@use '@cfpb/cfpb-design-system/src/elements/abstracts' as *;
 @use '@cfpb/cfpb-design-system/src/elements/base' as *;
 @use '@cfpb/cfpb-design-system/src/utilities' as *;
 @use '@cfpb/cfpb-design-system/src/components/cfpb-icons/icon';
-@use '../cfpb-utilities/transition/transition.scss' as *;
+@use '../cfpb-utilities/transition/transition.css' as *;
+@use '../../utilities/functions' as *;
 
 :host {
   // Theme
@@ -51,7 +50,7 @@
   button {
     // This line-height settings is larger than base.scss to
     // accommodate the SVG height.
-    line-height: math.div(21px, $base-font-size-px);
+    line-height: unitless-from-px(21px);
 
     // Remove default focus ring.
     outline: none;
@@ -133,7 +132,7 @@
       justify-content: space-between;
       align-items: center;
       gap: 10px;
-      padding-left: math.div(10px, $base-font-size-px) + em;
+      padding-left: rem-from-px(10px);
 
       cursor: pointer;
     }
@@ -151,7 +150,7 @@
       padding: 0;
 
       &::after {
-        padding-bottom: math.div(15px, $base-font-size-px) + em;
+        padding-bottom: rem-from-px(15px);
         width: 100%;
       }
     }

package/src/elements/cfpb-tag-filter/index.js

@@ -1,7 +1,7 @@
 import { LitElement, html, css, unsafeCSS } from 'lit';
 import { unsafeHTML } from 'lit/directives/unsafe-html.js';
-import styles from './cfpb-tag-filter.component.scss?inline';
-import icon from '../../components/cfpb-icons/icons/error.svg?raw';
+import styles from './styles.component.scss?inline';
+import { errorIcon as icon } from '../../components/cfpb-icons/icons-lib';
 
 /**
  *

package/src/elements/cfpb-tag-filter/{cfpb-tag-filter.component.scss → styles.component.scss}

@@ -1,23 +1,21 @@
-@use 'sass:math';
-@use '@cfpb/cfpb-design-system/src/elements/abstracts' as *;
-@use '@cfpb/cfpb-design-system/src/elements/cfpb-button/vars' as *;
+@use '../../utilities/functions' as *;
 
 :host {
   button {
     // This line-height isn't 19 or 22, as 20 creates a 30px high tag.
-    line-height: math.div(20px, $base-font-size-px);
+    line-height: unitless-from-px(20px);
 
     // Filter tags appear in filtered contexts, often as part of multiselects.
-    font-size: math.div(16px, $btn-font-size) + rem;
+    font-size: rem-from-px(16px);
 
     display: flex;
-    gap: math.div(10px, $btn-font-size) + rem;
+    gap: rem-from-px(10px);
     align-items: center;
 
     border: 1px solid var(--teal);
     padding: 4px 6px;
     background-color: var(--teal-20);
-    border-radius: math.div(3px, $base-font-size-px) + rem;
+    border-radius: rem-from-px(3px);
     color: var(--black);
     text-align: left;
     min-width: fit-content;
@@ -43,7 +41,7 @@
     // Prevent flexbox from squishing icon when tag text is long.
     flex: none;
 
-    height: math.div(19px, $btn-font-size) + rem;
+    height: rem-from-px(19px);
   }
 
   // If the contents are wrapped in a label, negate the label's display.

package/src/elements/cfpb-tag-group/index.js

@@ -1,5 +1,5 @@
 import { LitElement, html, css, unsafeCSS } from 'lit';
-import styles from './cfpb-tag-group.component.scss?inline';
+import styles from './styles.component.scss?inline';
 import { parseChildData } from '../cfpb-utilities/parse-child-data';
 
 const SUPPORTED_TAG_LIST = ['CFPB-TAG-FILTER', 'CFPB-TAG-TOPIC'];

package/src/elements/cfpb-tag-group/{cfpb-tag-group.component.scss → styles.component.scss}

@@ -1,6 +1,5 @@
-@use 'sass:math';
 @use '@cfpb/cfpb-design-system/src/elements/abstracts' as *;
-@use '@cfpb/cfpb-design-system/src/elements/cfpb-button/vars' as *;
+@use '../../utilities/functions' as *;
 
 :host {
   // Tag group sets the spacing between tags.
@@ -17,7 +16,7 @@
     // Tablet and above.
     @include respond-to-min($bp-sm-min) {
       display: flex;
-      gap: math.div(15px, $btn-font-size) + rem;
+      gap: rem-from-px(15px);
       flex-wrap: wrap;
 
       &[stacked] {
@@ -28,7 +27,7 @@
 
     &:has(cfpb-tag-filter) {
       display: flex;
-      gap: math.div(15px, $btn-font-size) + rem;
+      gap: rem-from-px(15px);
       flex-wrap: wrap;
     }
   }

package/src/elements/cfpb-tag-topic/index.js

@@ -1,5 +1,5 @@
 import { LitElement, html, css, unsafeCSS } from 'lit';
-import styles from './cfpb-tag-topic.component.scss?inline';
+import styles from './styles.component.scss?inline';
 
 /**
  *

package/src/elements/cfpb-tag-topic/{cfpb-tag-topic.component.scss → styles.component.scss}

@@ -1,15 +1,15 @@
-@use 'sass:math';
 @use '@cfpb/cfpb-design-system/src/elements/base' as *;
 @use '@cfpb/cfpb-design-system/src/elements/abstracts' as *;
 @use '@cfpb/cfpb-design-system/src/utilities' as *;
 @use '@cfpb/cfpb-design-system/src/components/cfpb-typography/mixins' as *;
+@use '../../utilities/functions' as *;
 
 :host {
   // Topic tags
   .a-tag-topic {
     text-decoration: none;
     display: flex;
-    gap: math.div(5px, $btn-font-size) + rem;
+    gap: rem-from-px(5px);
   }
 
   @include u-jump-link(

package/src/elements/cfpb-tagline/index.js

@@ -1,6 +1,6 @@
 import { LitElement, html, css, unsafeCSS } from 'lit';
 import { CfpbFlagUsa } from '../cfpb-flag-usa';
-import styles from './cfpb-tagline.component.scss?inline';
+import styles from './styles.component.scss?inline';
 
 /**
  * @element cfpb-icon-text

package/src/elements/cfpb-tagline/skeleton.css

@@ -0,0 +1,7 @@
+cfpb-tagline:not(:defined) {
+  min-height: 16.5px;
+}
+
+cfpb-tagline[islarge]:not(:defined) {
+  min-height: 22px;
+}

package/src/elements/cfpb-tagline/{cfpb-tagline.component.scss → styles.component.scss}

@@ -1,9 +1,8 @@
-@use 'sass:math';
-@use '@cfpb/cfpb-design-system/src/elements/abstracts' as *;
+@use '../../utilities/functions' as *;
 
 :host {
   .a-tagline {
-    font-size: math.div(12px, $base-font-size-px) + rem;
+    font-size: rem-from-px(12px);
 
     display: grid;
     grid-template-columns: 22px 1fr;
@@ -19,7 +18,7 @@
     }
 
     &--large {
-      font-size: math.div(16px, $base-font-size-px) + rem;
+      font-size: rem-from-px(16px);
 
       & cfpb-flag-usa {
         margin-top: 4px;

package/src/elements/cfpb-utilities/fallback/wc-fallback.css

@@ -0,0 +1,31 @@
+/*
+This fallback CSS assumes a web component that contains a <noscript> fallback,
+as well as author-supplied content, and separately has a script to swap the
+<noscript> with `<div class="fallback">` if JS is enabled, but the web component
+definition is not defined.
+
+Ex.
+
+<cfpb-example-btn hasfallback>
+  <!-- author-supplied no-js fallback -->
+  <noscript><button>Click this basic button!</button>
+
+  <!-- author-supplied slotted content -->
+  Click this fancy button!
+</cfpb-example-btn>
+*/
+
+/* 1. If JS is disabled, hide everything except <noscript> */
+[hasfallback] > :not(noscript) {
+  display: none;
+}
+
+/* 2. If JS is enabled, but web component definition is not defined, show fallback. */
+[hasfallback] > .fallback {
+  display: block;
+}
+
+/* 3. If JS is enabled and web component definition is defined, operate as normal. */
+[hasfallback]:defined > :not(noscript) {
+  display: block;
+}

package/src/elements/cfpb-utilities/fallback/wc-fallback.js

@@ -0,0 +1,65 @@
+/**
+ * This utility IIFE function can be added to a page with web components
+ * to support the display of any fallback content in `<noscript>` tags
+ * that would otherwise not appear if JavaScript was enabled, but
+ * the Web Component APIs were not supported.
+ */
+(function () {
+  /**
+   * Within a custom element (web component),
+   * convert any `<noscript>` tags into `<div class="fallback">`,
+   * so that the fallback content appears in environments where
+   * JavaScript is enabled, but web component APIs are not supported.
+   * @param {HTMLElement} el - A custom element.
+   */
+  function applyFallback(el) {
+    if (!el) return;
+
+    const tag = el.tagName.toLowerCase();
+    const isDefined = !!customElements.get(tag);
+    const noscript = el.querySelector('noscript');
+
+    // Only act if the element is NOT defined and there is a <noscript>
+    if (!isDefined && noscript) {
+      // Create a <div> with the fallback content.
+      const fallbackDiv = document.createElement('div');
+      fallbackDiv.className = 'fallback';
+      fallbackDiv.innerHTML = noscript.innerHTML;
+
+      // Insert fallback at the top.
+      el.insertBefore(fallbackDiv, el.firstChild);
+
+      // Hide the original <noscript> to avoid duplicates.
+      noscript.style.display = 'none';
+
+      /*
+    // Hide other non-fallback children (optional; wc-fallback.css handles this).
+    Array.from(el.children).forEach((child) => {
+      if (child !== fallbackDiv && child !== noscript) {
+        child.style.display = 'none';
+      }
+    });
+    */
+    }
+  }
+
+  /**
+   * Query the document for custom elements that have the "fallback" attribute,
+   * e.g. <my-custom-btn fallback>
+   * @param {string} selector - The CSS selector to search for on the page.
+   */
+  function applyAllFallbacks(selector = '[fallback]') {
+    document.querySelectorAll(selector).forEach((el) => applyFallback(el));
+  }
+
+  // Check for browser support of the Web Component APIs.
+  const supportsWC =
+    'customElements' in window &&
+    'attachShadow' in Element.prototype &&
+    'content' in document.createElement('template');
+
+  // Only run the fallback utility script globally if web components are NOT supported.
+  if (!supportsWC) {
+    document.addEventListener('DOMContentLoaded', applyAllFallbacks);
+  }
+})();