@cfpb/cfpb-design-system 4.0.4 → 4.2.0

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

@@ -0,0 +1,211 @@
+import { html, LitElement, css, unsafeCSS } from 'lit';
+import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+import styles from './cfpb-pagination.component.scss';
+import leftIcon from '../../components/cfpb-icons/icons/left.svg';
+import rightIcon from '../../components/cfpb-icons/icons/right.svg';
+import { I18nService, MediaQueryService } from '../cfpb-utilities/';
+
+/**
+ *
+ * @element cfpb-button
+ * @slot - The main content for the button.
+ */
+export class CfpbPagination extends LitElement {
+  #mediaService;
+  #isMobile;
+  #i18n;
+
+  static styles = css`
+    ${unsafeCSS(styles)}
+  `;
+
+  /**
+   * @property {number} currentPage - The currently selected page.
+   * @property {number} maxPage - The maximum page count.
+   * @returns {object} The map of properties.
+   */
+  static get properties() {
+    return {
+      currentPage: { type: Number, attribute: 'value', reflect: true },
+      maxPage: { type: Number, attribute: 'max', reflect: true },
+      lang: { type: String, reflect: true },
+    };
+  }
+
+  constructor() {
+    super();
+    this.currentPage = 1;
+    this.maxPage = 1;
+    this.#mediaService = new MediaQueryService();
+    this.#isMobile = false;
+    this.lang = 'en';
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.#i18n = this.querySelector('i18n-service');
+    if (this.#i18n) {
+      this.addEventListener('i18n-change', this.#onI18nChange);
+      this.#i18n.language = this.lang;
+    }
+  }
+
+  #onI18nChange() {
+    const updateLabel = (selector, key) => {
+      const btn = this.renderRoot.querySelector(selector);
+      const span = btn.querySelector('span');
+      if (btn) {
+        const newText = this.#i18n.translate(key);
+        span.innerHTML = newText;
+        btn.requestUpdate();
+      }
+    };
+
+    updateLabel('#previous', 'previous');
+    updateLabel('#next', 'next');
+    updateLabel('#go', 'go');
+
+    this.requestUpdate();
+  }
+
+  firstUpdated() {
+    this.#mediaService.addEventListener('change', this.#onMediaChange);
+    this.#isMobile = this.#mediaService.matches.xs;
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.#mediaService.removeEventListener('change', this.#onMediaChange);
+    this.#mediaService.destroy();
+  }
+
+  #onMediaChange = (event) => {
+    const newIsMobile = event.detail.matches.xs;
+    if (newIsMobile !== this.#isMobile) {
+      this.#isMobile = newIsMobile;
+      this.requestUpdate();
+    }
+  };
+
+  updated(changed) {
+    if (changed.has('currentPage') || changed.has('maxPage')) {
+      if (this.currentPage < 1) this.currentPage = 1;
+      else if (this.currentPage > this.maxPage) this.currentPage = this.maxPage;
+    }
+
+    if (changed.has('lang')) {
+      this.#i18n.language = this.lang;
+
+      this.requestUpdate();
+    }
+  }
+
+  get isAtMin() {
+    return this.currentPage <= 1;
+  }
+
+  get isAtMax() {
+    return this.currentPage >= this.maxPage;
+  }
+
+  #onInput(event) {
+    this.currentPage = event.target.value;
+  }
+
+  #handleSubmit(event) {
+    event.preventDefault();
+    const page = parseInt(this.currentPage, 10);
+    if (!Number.isNaN(page)) {
+      this.#goto(page);
+    }
+  }
+
+  #goto(page) {
+    const clamped = Math.max(1, Math.min(page, this.maxPage));
+    if (clamped !== this.currentPage) {
+      this.currentPage = clamped;
+      this.dispatchEvent(
+        new CustomEvent('page-change', {
+          detail: { page: clamped },
+          bubbles: true,
+          composed: true,
+        }),
+      );
+    }
+  }
+
+  render() {
+    // Get a translator function.
+    const trans =
+      this.#i18n && this.#i18n.translate
+        ? this.#i18n.translate.bind(this.#i18n)
+        : (key) => key;
+
+    return html`
+      <slot></slot>
+      <nav
+        class="m-pagination"
+        role="navigation"
+        aria-label="${trans('page number')}"
+      >
+        <cfpb-button
+          class="m-pagination__btn-prev"
+          id="next"
+          href="#"
+          ?flush-right=${!this.#isMobile}
+          ?disabled=${this.isAtMin}
+          @click=${() => this.#goto(this.currentPage - 1)}
+        >
+          ${unsafeSVG(leftIcon)} ${trans('next')}
+        </cfpb-button>
+
+        <form
+          class="m-pagination__form"
+          action="#pagination_content"
+          @submit=${this.#handleSubmit}
+        >
+          <label class="m-pagination__label">
+            ${trans('page')}
+            <span class="u-visually-hidden">
+              ${this.currentPage} ${trans('out of')} ${this.maxPage}
+              ${trans('total pages')}
+            </span>
+            <input
+              class="m-pagination__current-page"
+              name="page"
+              type="number"
+              min="1"
+              max=${this.maxPage}
+              pattern="[0-9]*"
+              inputmode="numeric"
+              .value=${this.currentPage}
+              @input=${this.#onInput}
+            />
+            ${trans('of')} ${this.maxPage}
+          </label>
+          <cfpb-button id="go" type="submit" style-as-link>
+            ${trans('go')}
+          </cfpb-button>
+        </form>
+
+        <cfpb-button
+          class="m-pagination__btn-next"
+          id="previous"
+          href="#"
+          ?flush-left=${!this.#isMobile}
+          ?disabled=${this.isAtMax}
+          @click=${() => this.#goto(this.currentPage + 1)}
+        >
+          ${trans('previous')} ${unsafeSVG(rightIcon)}
+        </cfpb-button>
+      </nav>
+    `;
+  }
+
+  static init() {
+    I18nService.init();
+
+    window.customElements.get('cfpb-pagination') ||
+      window.customElements.define('cfpb-pagination', CfpbPagination);
+  }
+}

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

@@ -14,7 +14,8 @@ export class CfpbTagFilter extends LitElement {
   `;
 
   /**
-   * @property {string} for - Whether to stack the tags vertically.
+   * @property {string} for - Associate the label with an ID elsewhere.
+   * @returns {object} The map of properties.
    */
   static get properties() {
     return {

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

@@ -31,7 +31,7 @@ describe('<cfpb-tag-filter>', () => {
     expect(assignedNodes[0].textContent).toBe('Earth');
   });
 
-  xit('dispatches the correct event', async () => {
+  it('dispatches the correct event', async () => {
     const mockHandler = jest.fn();
     elm.addEventListener('tag-click', mockHandler);
 

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

@@ -23,6 +23,7 @@ export class CfpbTagGroup extends LitElement {
   /**
    * @property {boolean} stacked - Whether to stack the tags vertically.
    * @property {Array} tagList - List of the tags in the tag group.
+   * @returns {object} The map of properties.
    */
   static get properties() {
     return {
@@ -87,7 +88,7 @@ export class CfpbTagGroup extends LitElement {
 
   /**
    * Handle a change of the light DOM.
-   * @param {MutationRecord} mutationList
+   * @param {MutationRecord} mutationList - The record of observed DOM changes.
    */
   #onMutation(mutationList) {
     if (!this.#initialized) return;

package/src/elements/cfpb-tag-topic/cfpb-tag-topic.component.scss

@@ -26,6 +26,7 @@
     a.a-tag-topic--no-top-border {
       position: relative;
       border-top: none;
+      border-top-style: none !important;
     }
 
     a.a-tag-topic:hover::before,
@@ -63,6 +64,7 @@
     a.a-tag-topic:hover,
     a.a-tag-topic:focus,
     a.a-tag-topic:active {
+      text-decoration: none;
       border-bottom: none;
       outline-offset: 1px;
 

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

@@ -15,6 +15,7 @@ export class CfpbTagTopic extends LitElement {
    * @property {string} href - href attribute, if this is a topic link.
    * @property {boolean} siblingOfJumpLink
    *   Whether the preceding sibling is a jump link or not.
+   * @returns {object} The map of properties.
    */
   static get properties() {
     return {
@@ -23,6 +24,12 @@ export class CfpbTagTopic extends LitElement {
     };
   }
 
+  /*
+   * @property {string} href - The URL to link to (makes the tag a link).
+   * @property {boolean} siblingOfJumpLink
+   *   Whether the preceding sibling is a link or not. This is used to stack the
+   *   divider lines between the links at mobile.
+   */
   constructor() {
     super();
     this.href = '';

package/src/elements/cfpb-utilities/i18n-service.js

@@ -0,0 +1,128 @@
+/**
+ * A service for embedding and using translations via markup.
+ *
+ * Expect markup like:
+ * <i18n-service>
+ *   <template>
+ *     {
+ *       "en": { "hello": "Hello", "good afternoon": "Good afternoon" },
+ *       "es": { "hello": "Hola", "good afternoon": "Buenas tardes" }
+ *     }
+ *   </template>
+ * </i18n-service>
+ */
+export class I18nService extends HTMLElement {
+  #translations;
+  #language;
+
+  constructor() {
+    super();
+    this.#translations = {};
+    this.#language = '';
+  }
+
+  connectedCallback() {
+    const errors = [];
+    const template = this.querySelector('template');
+    if (!template) {
+      errors.push([
+        'missing-template',
+        'No <template> found inside <i18n-service>',
+      ]);
+      return;
+    }
+
+    try {
+      const json = template.innerHTML.trim();
+      const data = JSON.parse(json);
+
+      if (typeof data !== 'object' || Array.isArray(data)) {
+        errors.push([
+          'invalid-format',
+          'Translations JSON must be an object keyed by the language codes',
+        ]);
+      }
+
+      this.#translations = data;
+
+      // Set default lanugage to the first available one, if not already set.
+      const available = this.availableLanguages;
+      if (available.length > 0 && !this.#language) {
+        this.language = available[0];
+      }
+    } catch (err) {
+      errors.push([
+        'parse-error',
+        'Failed to parse i18n template JSON',
+        { err },
+      ]);
+    }
+
+    // Aggregate any errors together and dispatch them when the app has
+    // refreshed, which gives other components a chance to listen for them.
+    requestAnimationFrame(() => {
+      errors.forEach((error) => {
+        this.#dispatchError(...error);
+      });
+    });
+  }
+
+  /**
+   * Set the current language
+   * @param {string} lang - Language code (e.g. "en", "es", "ar", "ru", etc.)
+   */
+  set language(lang) {
+    if (!this.#translations[lang]) {
+      this.#dispatchError('invalid-language', `Unsupported language: ${lang}`, {
+        lang,
+      });
+      return;
+    }
+
+    if (this.#language !== lang) {
+      this.#language = lang;
+      this.dispatchEvent(
+        new CustomEvent('i18n-change', {
+          detail: { language: lang },
+          bubbles: true,
+          composed: true,
+        }),
+      );
+    }
+  }
+
+  /**
+   * @returns {string} The currently set language.
+   */
+  get language() {
+    return this.#language;
+  }
+
+  get availableLanguages() {
+    return Object.keys(this.#translations);
+  }
+
+  /**
+   * Translate a language key.
+   * @param {string} key - An arbitrary key from the <template>.
+   * @returns {string} The translation.
+   */
+  translate(key) {
+    return this.#translations[this.#language]?.[key] || key;
+  }
+
+  #dispatchError(type, message, extra = {}) {
+    this.dispatchEvent(
+      new CustomEvent('i18n-error', {
+        detail: { type, message, ...extra },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  static init() {
+    window.customElements.get('i18n-service') ||
+      window.customElements.define('i18n-service', I18nService);
+  }
+}

package/src/elements/cfpb-utilities/i18n-service.spec.js

@@ -0,0 +1,156 @@
+import { describe, jest } from '@jest/globals';
+import { I18nService } from './i18n-service';
+
+I18nService.init();
+
+describe('I18Service', () => {
+  let elm;
+  beforeEach(() => {
+    jest.useFakeTimers();
+    elm = document.createElement('i18n-service');
+    document.body.appendChild(elm);
+  });
+
+  afterEach(() => {
+    document.body.removeChild(elm);
+    jest.useRealTimers();
+  });
+
+  xdescribe('connectedCallback and template parsing', () => {
+    it('dispatches error when template is missing', async () => {
+      elm.addEventListener('i18n-error', (evt) => {
+        expect(evt.detail.type).toBe('missing-template');
+        expect(evt.detail.message).toMatch(/No <template> found/);
+      });
+      elm.connectedCallback();
+      // We expect requestAnimationFrame to schedule the dispatch: flush it.
+      await jest.runOnlyPendingTimers();
+    });
+
+    it('dispatches parse-error when JSON is invalid', async () => {
+      const tpl = document.createElement('template');
+      tpl.innerHTML = '{ invalid json }';
+      elm.appendChild(tpl);
+
+      elm.addEventListener('i18n-error', (evt) => {
+        expect(evt.detail.type).toBe('parse-error');
+        expect(evt.detail.message).toMatch(/Failed to parse/);
+        expect(evt.detail.err).toBeDefined();
+      });
+
+      elm.connectedCallback();
+      await jest.runOnlyPendingTimers();
+    });
+
+    it('dispatches invalid-format when JSON is an array or not object', async () => {
+      const tpl = document.createElement('template');
+      tpl.innerHTML = JSON.stringify(['a', 'b', 'c']);
+      elm.appendChild(tpl);
+
+      elm.addEventListener('i18n-error', (evt) => {
+        expect(evt.detail.type).toBe('invalid-format');
+        expect(evt.detail.message).toMatch(/must be an object/);
+      });
+
+      elm.connectedCallback();
+      await jest.runOnlyPendingTimers();
+    });
+
+    it('parses valid JSON and sets default language', () => {
+      const translations = {
+        en: { hello: 'Hello' },
+        es: { hello: 'Hola' },
+      };
+
+      const tpl = document.createElement('template');
+      tpl.innerHTML = JSON.stringify(translations);
+      elm.appendChild(tpl);
+
+      elm.connectedCallback();
+      jest.runOnlyPendingTimers();
+
+      expect(elm.language).toBe('en');
+      expect(elm.availableLanguages).toEqual(['en', 'es']);
+      expect(elm.translate('hello')).toBe('Hello');
+    });
+  });
+
+  describe('language setter/getter and events', () => {
+    beforeEach(() => {
+      const translations = {
+        en: { a: 'A' },
+        es: { a: 'Une' },
+      };
+
+      const tpl = document.createElement('template');
+      tpl.innerHTML = JSON.stringify(translations);
+      elm.appendChild(tpl);
+    });
+
+    it('does not dispatch event or set if invalid language', async () => {
+      elm.addEventListener('i18n-error', (evt) => {
+        expect(evt.detail.type).toBe('invalid-language');
+        expect(evt.detail.message).toMatch(/Unsupported language/);
+      });
+      elm.connectedCallback();
+      await jest.runOnlyPendingTimers();
+
+      elm.language = 'de';
+      expect(elm.language).toBe('en');
+    });
+
+    it('switching to valid language dispatches i18n-change event', async () => {
+      elm.connectedCallback();
+      await jest.runOnlyPendingTimers();
+
+      elm.addEventListener('i18n-change', (evt) => {
+        expect(evt.detail.language).toBe('es');
+      });
+
+      elm.language = 'es';
+      expect(elm.language).toBe('es');
+    });
+
+    it('assigning the same language does not re-dispatch change', async () => {
+      elm.connectedCallback();
+      await jest.runOnlyPendingTimers();
+      const spy = jest.fn();
+
+      elm.addEventListener('i18n-change', spy);
+      elm.language = 'es';
+      elm.language = 'es';
+      expect(spy).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('translate()', () => {
+    beforeEach(() => {
+      const translations = {
+        en: { hello: 'Hello' },
+        es: { hello: 'Hola' },
+      };
+
+      const tpl = document.createElement('template');
+      tpl.innerHTML = JSON.stringify(translations);
+      elm.appendChild(tpl);
+    });
+
+    it('returns correct translation for existing key', async () => {
+      elm.connectedCallback();
+      await jest.runOnlyPendingTimers();
+
+      expect(elm.translate('hello')).toBe('Hello');
+      elm.language = 'es';
+      expect(elm.translate('hello')).toBe('Hola');
+    });
+
+    it('falls back to key if missing translation', () => {
+      expect(elm.translate('nonexistent')).toBe('nonexistent');
+    });
+
+    it('returns key if translations or language not set', () => {
+      const e2 = document.createElement('i18n-service');
+      expect(e2.translate('whatever')).toBe('whatever');
+    });
+  });
+});

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

@@ -0,0 +1,7 @@
+/* ==========================================================================
+   Design System - Web Components
+   ========================================================================== */
+
+// TODO: aggregate and export the component subdirectories automatically.
+export * from './i18n-service';
+export * from './media-query-service';

package/src/elements/cfpb-utilities/media-query-service.js

@@ -0,0 +1,102 @@
+/**
+ * A service for observing named breakpoints via matchMedia.
+ * Emits a `change` event (CustomEvent) whenever any breakpoint match status changes.
+ * Consumers can also call `matches` or `is(breakpointName)` to get current state.
+ */
+export class MediaQueryService extends EventTarget {
+  #breakpoints;
+  #mqls = new Map(); // Map<key, MediaQueryList>
+  #handlers = new Map(); // Map<key, listener>
+  #matches = new Map(); // Map<key, boolean>
+  #pendingUpdate = false;
+
+  /**
+   *
+   * @param {Record<string, {min: number, max?: number}} [breakpoints]
+   *   A map of breakpoint name -> { min: px, optional max: px }.
+   *   If not provided, default breakpoints are used.
+   */
+  constructor(breakpoints) {
+    super();
+
+    this.#breakpoints = breakpoints ?? {
+      xs: { min: 0, max: 600 },
+      sm: { min: 601, max: 900 },
+      med: { min: 901, max: 1020 },
+      lg: { min: 1021, max: 1200 },
+      xl: { min: 1201 },
+    };
+
+    // Setup each media query.
+    for (const [key, range] of Object.entries(this.#breakpoints)) {
+      const mqString = this.#rangeToMediaQuery(range);
+      const mql = window.matchMedia(mqString);
+
+      this.#mqls.set(key, mql);
+      this.#matches.set(key, mql.matches);
+
+      const listener = (evt) => {
+        this.#matches.set(key, evt.matches);
+
+        if (!this.#pendingUpdate) {
+          this.#pendingUpdate = true;
+
+          requestAnimationFrame(() => {
+            this.#pendingUpdate = false;
+            this.#dispatchChange(); // Dispatch only once per frame.
+          });
+        }
+
+        /*
+        const prev = this.#matches.get(key);
+        if (prev !== evt.matches) {
+          this.#matches.set(key, evt.matches);
+          this.#dispatchChange();
+        }
+        */
+      };
+
+      mql.addEventListener('change', listener);
+
+      this.#handlers.set(key, listener);
+    }
+
+    // Emit initial state.
+    this.#dispatchChange();
+  }
+
+  #rangeToMediaQuery(range) {
+    const parts = [];
+    if (range.min != null) {
+      parts.push(`(min-width: ${range.min}px)`);
+    }
+    if (range.max != null) {
+      parts.push(`(max-width: ${range.max}px)`);
+    }
+    return parts.join(' and ');
+  }
+
+  #dispatchChange() {
+    const detail = {
+      matches: Object.fromEntries(this.#matches),
+    };
+
+    this.dispatchEvent(new CustomEvent('change', { detail }));
+  }
+
+  get matches() {
+    return Object.fromEntries(this.#matches);
+  }
+
+  destroy() {
+    for (const [key, mql] of this.#mqls.entries()) {
+      const listener = this.#handlers.get(key);
+      if (!listener) continue;
+      mql.removeEventListener('change', listener);
+    }
+
+    this.#mqls.clear();
+    this.#handlers.clear();
+    this.#matches.clear();
+  }
+}