@cfpb/cfpb-design-system 4.1.0 → 4.2.1

package/src/elements/cfpb-pagination/cfpb-pagination.component.scss

@@ -0,0 +1,72 @@
+@use 'sass:math';
+@use '@cfpb/cfpb-design-system/src/abstracts' as *;
+@use '@cfpb/cfpb-design-system/src/utilities' as *;
+
+:host {
+  width: 100%;
+
+  .cf-icon-svg {
+    height: $cf-icon-height;
+    vertical-align: middle;
+    fill: currentcolor;
+  }
+
+  .m-pagination {
+    display: grid;
+    grid-template-columns: auto 1fr auto;
+    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;
+
+    &__form {
+      grid-area: pag-form;
+      display: flex;
+      flex-flow: wrap;
+      place-content: center;
+      gap: math.div(10px, $base-font-size-px) + rem;
+
+      padding: math.div(5px, $base-font-size-px) + rem;
+      border-radius: math.div(4px, $base-font-size-px) + rem;
+      background: var(--gray-5);
+      color: var(--gray);
+    }
+
+    &__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;
+
+      font-weight: 500;
+      text-align: right;
+    }
+
+    &__label {
+      display: contents;
+      white-space: nowrap;
+    }
+
+    &__btn-prev {
+      grid-area: pag-btn-prev;
+      z-index: 1;
+    }
+    &__btn-next {
+      grid-area: pag-btn-next;
+      z-index: 1;
+    }
+
+    // Tablet and above.
+    @include respond-to-min($bp-sm-min) {
+      grid-template-areas: 'pag-btn-prev pag-form pag-btn-next';
+
+      &__btn-prev {
+        border-top-right-radius: 0;
+        border-bottom-right-radius: 0;
+      }
+      &__btn-next {
+        border-top-left-radius: 0;
+        border-bottom-left-radius: 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

@@ -15,6 +15,7 @@ export class CfpbTagFilter extends LitElement {
 
   /**
    * @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-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 {

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';