@cfpb/cfpb-design-system 4.0.2 → 4.0.4

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

@@ -0,0 +1,311 @@
+import { html, LitElement, css, unsafeCSS } from 'lit';
+import styles from './cfpb-tag-group.component.scss';
+
+const SUPPORTED_TAG_LIST = ['CFPB-TAG-FILTER', 'CFPB-TAG-TOPIC'];
+
+/**
+ * @element cfpb-tag-group.
+ * @description A group of tags (filter or topic tags) that can be added and
+ *   removed.
+ *
+ *   The tag group has a list of tags in the lightDOM that gets re-written
+ *   inside an unordered list in the shadowDOM so that it is read out
+ *   as a list of items in VoiceOver.
+ * @attribute {string} lang - The element's language.
+ * @fires addtag - A tag was added to the group.
+ * @fires removetag - A tag was removed from the group.
+ */
+export class CfpbTagGroup extends LitElement {
+  static styles = css`
+    ${unsafeCSS(styles)}
+  `;
+
+  /**
+   * @property {boolean} stacked - Whether to stack the tags vertically.
+   * @property {Array} tagList - List of the tags in the tag group.
+   */
+  static get properties() {
+    return {
+      stacked: { type: Boolean, reflect: true },
+      tagList: { type: Array },
+    };
+  }
+
+  // Private properties.
+  #observer;
+  #initialized = false;
+  #tagMap;
+
+  constructor() {
+    super();
+    this.stacked = false;
+    this.tagList = [];
+    this.#observer = new MutationObserver(this.#onMutation.bind(this));
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.#observeLightDom();
+  }
+
+  disconnectedCallback() {
+    this.#observer.disconnect();
+    super.disconnectedCallback();
+  }
+
+  firstUpdated() {
+    // Wait for the browser to complete its render cycle.
+    requestAnimationFrame(() => {
+      // Add the tags from the light DOM.
+      SUPPORTED_TAG_LIST.forEach((tagName) => {
+        const tags = this.querySelectorAll(`${tagName.toLowerCase()}`);
+        tags.forEach((tag) => this.addTag(tag));
+      });
+
+      this.#initialized = true;
+    });
+  }
+
+  /**
+   * Set up a MutationObserver to watch changes in the light DOM.
+   */
+  #observeLightDom() {
+    this.#observer.observe(this, {
+      childList: true,
+      subtree: false,
+    });
+  }
+
+  /**
+   * Whether a particular node tagName is supported as a tag of this tag group.
+   * @param {string} tagName - The name of a supported custom element tag.
+   * @returns {boolean} true if the tagName is supported, false otherwise.
+   */
+  #supportedTag(tagName) {
+    return SUPPORTED_TAG_LIST.includes(tagName);
+  }
+
+  /**
+   * Handle a change of the light DOM.
+   * @param {MutationRecord} mutationList
+   */
+  #onMutation(mutationList) {
+    if (!this.#initialized) return;
+    for (const mutation of mutationList) {
+      // Ignore mutations that occur within the shadow DOM.
+      if (mutation.type === 'childList') {
+        mutation.addedNodes.forEach((node) => this.#handleNodeAdded(node));
+        mutation.removedNodes.forEach((node) => this.#handleNodeRemoved(node));
+      }
+    }
+  }
+
+  /**
+   * @param {Node} node - The node that was added to the light DOM.
+   */
+  #handleNodeAdded(node) {
+    if (this.#supportedTag(node.tagName)) {
+      const index = Array.from(this.children).indexOf(node);
+      this.addTag(node, index);
+    }
+  }
+
+  /**
+   * @param {Node} node - The node that was removed from the light DOM.
+   */
+  #handleNodeRemoved(node) {
+    if (this.#supportedTag(node.tagName)) {
+      this.#removeTagNode(node);
+    }
+  }
+
+  /**
+   * Refresh the tagList property from the DOM list.
+   */
+  #refreshTagList() {
+    this.tagList = [...this.renderRoot.querySelectorAll('ul li > *')];
+
+    // Iterate over the list, and if there are topic tag links adjacent to each
+    // other, then we set the siblingOfJumpLink property, which adjusts the
+    // styles for adjacent jumplinks so that the borders aren't doubled up.
+    if (this.tagList.length > 0) {
+      let lastItemIsLink = false;
+      this.tagList.forEach((item) => {
+        if (lastItemIsLink) {
+          item.siblingOfJumpLink = true;
+          lastItemIsLink = false;
+        }
+        if (item.href !== '') {
+          lastItemIsLink = true;
+        }
+      });
+    }
+  }
+
+  /**
+   * Add a tag to the light and dark DOM.
+   * @param {*} tag - The tag to add.
+   * @param {number} index - The position at which to add the tag.
+   * @returns {boolean} false if the tag is already in the light DOM.
+   */
+  addTag(tag, index = -1) {
+    const alreadyInDom = Array.from(this.children).includes(tag);
+
+    if (!alreadyInDom) {
+      this.#insertIntoLightDom(tag, index);
+      return false;
+    }
+
+    this.#insertIntoShadowDom(tag, index);
+
+    this.#refreshTagList();
+  }
+
+  /**
+   * Add a tag to the light DOM.
+   * @param {*} tag - The tag to add.
+   * @param {number} index - The position at which to add the tag.
+   */
+  #insertIntoLightDom(tag, index) {
+    if (index === -1 || index >= this.children.length) {
+      this.appendChild(tag);
+    } else {
+      this.insertBefore(tag, this.children[index]);
+    }
+  }
+
+  /**
+   * Add a tag to the shadow DOM.
+   * @param {*} tag - The tag to add.
+   * @param {number} index - The position at which to add the tag.
+   */
+  #insertIntoShadowDom(tag, index) {
+    const cloned = tag.cloneNode(true);
+    const wrapped = document.createElement('li');
+    wrapped.appendChild(cloned);
+
+    const ul = this.shadowRoot.querySelector('ul');
+
+    let actualIndex = index;
+    if (index === -1 || index >= ul.children.length) {
+      ul.appendChild(wrapped);
+      actualIndex = ul.children.length - 1;
+    } else {
+      ul.insertBefore(wrapped, ul.children[index]);
+    }
+
+    cloned.addEventListener('tag-click', () => {
+      this.dispatchEvent(
+        new CustomEvent('tag-click', {
+          detail: { target: cloned, index: actualIndex },
+          bubbles: true,
+          composed: true,
+        }),
+      );
+      this.#removeTagNode(cloned);
+    });
+
+    this.#tagMap ??= new Map();
+    const id = this.#tagIdentifier(tag);
+    this.#tagMap.set(id, wrapped);
+
+    this.dispatchEvent(
+      new CustomEvent('tag-added', {
+        detail: { target: tag, index: actualIndex },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  /**
+   * @param {*} tag - The tag to add.
+   * @returns {string} A unique ID.
+   */
+  #tagIdentifier(tag) {
+    return `${tag.tagName}::${tag.textContent.trim()}`;
+  }
+
+  /**
+   * Remove a filter tag from the light DOM.
+   * This is private because it's called by the mutation observer.
+   * @param {*} tag - The tag to remove.
+   * @returns {boolean} false if the wrapped tag was not found.
+   */
+  #removeTagNode(tag) {
+    const id = this.#tagIdentifier(tag);
+    const wrapped = this.#tagMap.get(id);
+
+    if (!wrapped) return false;
+
+    // Try getting the index from the light DOM.
+    let index = Array.from(this.children).indexOf(tag);
+
+    // If not found (e.g. manually removed via DevTools), fallback to shadow DOM.
+    if (index === -1 && wrapped.parentElement) {
+      const shadowChildren = Array.from(wrapped.parentElement.children);
+      index = shadowChildren.indexOf(wrapped);
+    }
+
+    // Remove from light DOM and shadow DOM.
+    if (tag.parentElement === this) {
+      tag.remove();
+    }
+
+    if (wrapped.parentElement) {
+      wrapped.remove();
+    }
+
+    this.#tagMap.delete(id);
+
+    this.dispatchEvent(
+      new CustomEvent('tag-removed', {
+        detail: { target: tag, index: index },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+
+    this.#refreshTagList();
+  }
+
+  /**
+   * Remove a filter tag from the light and dark DOM.
+   * @param {*} tag - The tag to remove.
+   */
+  removeTag(tag) {
+    // Support passing in either light DOM <tag> or shadow DOM <li> if needed
+    // Normalize to the light DOM tag element:
+
+    const lightDomTag = this.#getLightDomTag(tag);
+
+    this.#removeTagNode(lightDomTag);
+  }
+
+  /**
+   * Get light and dark DOM.
+   * @param {Node} node - The tag to remove.
+   * @returns {Node|null} The tag node.
+   */
+  #getLightDomTag(node) {
+    // If node is a wrapped shadow DOM <li>, get the orignal tag inside it.
+    if (node.tagName === 'LI' && node.shadowRoot) {
+      // unlikely scenario if you don't expose shadow nodes externally.
+      return node.querySelector('cfpb-tag-filter');
+    }
+
+    // If node is already a light DOM tag or child <cfpb-tag-group>, return it.
+    if (this.contains(node)) return node;
+
+    return null;
+  }
+
+  render() {
+    return html`<ul ?stacked=${this.stacked}></ul>`;
+  }
+
+  static init() {
+    window.customElements.get('cfpb-tag-group') ||
+      window.customElements.define('cfpb-tag-group', CfpbTagGroup);
+  }
+}

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

@@ -0,0 +1,160 @@
+import { jest } from '@jest/globals';
+import { CfpbTagFilter } from '../cfpb-tag-filter';
+import { CfpbTagTopic } from '../cfpb-tag-topic';
+import { CfpbTagGroup } from './index.js';
+
+describe('<cfpb-tag-group>', () => {
+  let elm;
+
+  beforeEach(async () => {
+    CfpbTagGroup.init();
+    CfpbTagTopic.init();
+    CfpbTagFilter.init();
+    elm = document.createElement('cfpb-tag-group');
+    document.body.appendChild(elm);
+
+    await customElements.whenDefined('cfpb-tag-group');
+    await elm.updateComplete;
+  });
+
+  afterEach(() => {
+    document.body.removeChild(elm);
+  });
+
+  it('renders slotted content', async () => {
+    const slottedContent = document.createElement('cfpb-tag-filter');
+    slottedContent.textContent = 'Earth';
+    elm.appendChild(slottedContent);
+    await elm.updateComplete;
+
+    // Wait for browser render to settle.
+    // Needed because requestAnimationFrame is used in firstUpdated.
+    await new Promise((resolve) => requestAnimationFrame(resolve));
+
+    const ul = elm.shadowRoot.querySelector('ul');
+
+    expect(ul.children.length).toBe(1);
+
+    // Walk into the first <li> and first <cfpb-tag-filter>.
+    expect(ul.firstElementChild.firstElementChild.textContent).toBe('Earth');
+  });
+
+  it('dispatches the correct events', async () => {
+    const mockAddedHandler = jest.fn();
+    const mockRemoveHandler = jest.fn();
+    elm.addEventListener('tag-added', mockAddedHandler);
+    elm.addEventListener('tag-removed', mockRemoveHandler);
+
+    const slottedContent = document.createElement('cfpb-tag-filter');
+    slottedContent.textContent = 'Earth';
+    elm.appendChild(slottedContent);
+    await elm.updateComplete;
+
+    // Wait for MutationObserver render to settle.
+    await new Promise((resolve) => {
+      elm.addEventListener('tag-added', () => {
+        resolve();
+      });
+    });
+
+    expect(mockAddedHandler).toHaveBeenCalledTimes(1);
+    expect(
+      mockAddedHandler.mock.calls[0][0].detail.target.isEqualNode(
+        slottedContent,
+      ),
+    ).toBe(true);
+
+    elm.shadowRoot
+      .querySelector('cfpb-tag-filter')
+      .shadowRoot.querySelector('button')
+      .click();
+
+    expect(mockRemoveHandler).toHaveBeenCalledTimes(1);
+    expect(
+      mockRemoveHandler.mock.calls[0][0].detail.target.isEqualNode(
+        slottedContent,
+      ),
+    ).toBe(true);
+  });
+
+  it('adds tags to internal list', async () => {
+    expect(elm.tagList.length).toBe(0);
+
+    let slottedContent = document.createElement('cfpb-tag-filter');
+    slottedContent.textContent = 'Earth';
+    elm.appendChild(slottedContent);
+    await elm.updateComplete;
+
+    // Wait for MutationObserver render to settle.
+    await new Promise((resolve) => {
+      elm.addEventListener('tag-added', () => {
+        resolve();
+      });
+    });
+
+    expect(elm.tagList.length).toBe(1);
+
+    slottedContent = document.createElement('cfpb-tag-filter');
+    slottedContent.textContent = 'Mars';
+    elm.appendChild(slottedContent);
+    await elm.updateComplete;
+
+    expect(elm.tagList.length).toBe(2);
+    expect(elm.tagList[1].isEqualNode(slottedContent)).toBe(true);
+  });
+
+  it('adds class to remove border on topic tag groups', async () => {
+    let slottedContent = document.createElement('cfpb-tag-topic');
+    slottedContent.textContent = 'Earth';
+    slottedContent.setAttribute('href', '#');
+    elm.appendChild(slottedContent);
+
+    slottedContent = document.createElement('cfpb-tag-topic');
+    slottedContent.textContent = 'Mars';
+    slottedContent.setAttribute('href', '#');
+    elm.appendChild(slottedContent);
+
+    // Wait for MutationObserver render to settle.
+    await new Promise((resolve) => {
+      elm.addEventListener('tag-added', () => {
+        resolve();
+      });
+    });
+
+    await elm.tagList[0].updateComplete;
+
+    expect(
+      elm.tagList[0].shadowRoot
+        .querySelector('a')
+        .classList.contains('a-tag-topic--no-top-border'),
+    ).toBe(false);
+    expect(
+      elm.tagList[1].shadowRoot
+        .querySelector('a')
+        .classList.contains('a-tag-topic--no-top-border'),
+    ).toBe(true);
+  });
+
+  it('adds and removes at chosen indices', async () => {
+    const earthContent = document.createElement('cfpb-tag-filter');
+    earthContent.textContent = 'Earth';
+    elm.addTag(earthContent);
+
+    const marsContent = document.createElement('cfpb-tag-filter');
+    marsContent.textContent = 'Mars';
+    elm.addTag(marsContent, 0);
+
+    // Wait for MutationObserver render to settle.
+    await new Promise((resolve) => {
+      elm.addEventListener('tag-added', () => {
+        resolve();
+      });
+    });
+
+    expect(elm.tagList[0].isEqualNode(marsContent)).toBe(true);
+
+    elm.removeTag(marsContent, 0);
+
+    expect(elm.tagList[0].isEqualNode(earthContent)).toBe(true);
+  });
+});

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

@@ -0,0 +1,88 @@
+@use 'sass:math';
+@use '@cfpb/cfpb-design-system/src/base' as *;
+@use '@cfpb/cfpb-design-system/src/abstracts' as *;
+@use '@cfpb/cfpb-design-system/src/utilities' as *;
+@use '@cfpb/cfpb-design-system/src/components/cfpb-typography/mixins' as *;
+
+:host {
+  // Topic tags
+  .a-tag-topic {
+    text-decoration: none;
+    display: flex;
+    gap: math.div(5px, $btn-font-size) + rem;
+  }
+
+  @include u-jump-link(
+    $jump-link-class: 'a-tag-topic',
+    $jump-link-text-class: 'a-tag-topic__text',
+    $is-gold: true
+  );
+
+  // @include u-jump-link-group($jump-link-class: 'a-tag-topic');
+
+  // Mobile only.
+  @include respond-to-max($bp-xs-max) {
+    // Handle the borders of jump links that are adjacent in a list.
+    a.a-tag-topic--no-top-border {
+      position: relative;
+      border-top: none;
+    }
+
+    a.a-tag-topic:hover::before,
+    a.a-tag-topic:focus::before {
+      position: absolute;
+      top: -1px;
+      content: '';
+      display: block;
+      height: 1px;
+      width: 100%;
+      border-top: 1px solid currentcolor;
+    }
+  }
+
+  .a-tag-topic__bullet {
+    font-size: 1rem;
+    line-height: 1rem;
+  }
+
+  // Tablet and above.
+  @include respond-to-min($bp-sm-min) {
+    a.a-tag-topic__text {
+      // Colors for :link, :visited, :hover, :focus, :active
+      @include u-link-colors(
+        var(--gray),
+        var(--gray),
+        var(--gray),
+        var(--gray),
+        var(--gray)
+      );
+    }
+
+    a.a-tag-topic,
+    a.a-tag-topic:visited,
+    a.a-tag-topic:hover,
+    a.a-tag-topic:focus,
+    a.a-tag-topic:active {
+      border-bottom: none;
+      outline-offset: 1px;
+
+      .a-tag-topic__text {
+        // Move the underline down 1px.
+        padding-bottom: 1px;
+        border-bottom: 1px dotted var(--gold-80);
+      }
+    }
+
+    a.a-tag-topic:hover .a-tag-topic__text {
+      border-bottom: 1px solid var(--gold-80);
+    }
+
+    a.a-tag-topic:focus {
+      outline-color: var(--gray);
+
+      .a-tag-topic__text {
+        border-bottom-style: solid !important;
+      }
+    }
+  }
+}

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

@@ -0,0 +1,62 @@
+import { html, LitElement, css, unsafeCSS } from 'lit';
+import styles from './cfpb-tag-topic.component.scss';
+
+/**
+ *
+ * @element cfpb-tag-topic.
+ * @slot - The content for the topic tag.
+ */
+export class CfpbTagTopic extends LitElement {
+  static styles = css`
+    ${unsafeCSS(styles)}
+  `;
+
+  /**
+   * @property {string} href - href attribute, if this is a topic link.
+   * @property {boolean} siblingOfJumpLink
+   *   Whether the preceding sibling is a jump link or not.
+   */
+  static get properties() {
+    return {
+      href: { type: String, reflect: true },
+      siblingOfJumpLink: { type: Boolean },
+    };
+  }
+
+  constructor() {
+    super();
+    this.href = '';
+    this.siblingOfJumpLink = false;
+  }
+
+  get #tagClass() {
+    let tagClass = 'a-tag-topic';
+
+    if (this.siblingOfJumpLink) {
+      tagClass += ' a-tag-topic--no-top-border';
+    }
+
+    return tagClass;
+  }
+
+  render() {
+    const bullet = html`<span class="a-tag-topic__bullet" aria-hidden="true"
+      >•</span
+    >`;
+    const slot =
+      this.href === ''
+        ? html`<span class="a-tag-topic"
+            >${bullet}<span class="a-tag-topic__text"><slot></slot></span
+          ></span>`
+        : html`<a class="${this.#tagClass}" href="${this.href}"
+            >${bullet}<span class="a-tag-topic__text"><slot></slot></span
+          ></a>`;
+    return html`${slot}`;
+  }
+
+  static init() {
+    // Initialize parent file upload.
+    window.customElements.get('cfpb-tag-topic') ||
+      window.customElements.define('cfpb-tag-topic', CfpbTagTopic);
+  }
+}

package/src/elements/index.js

@@ -0,0 +1,11 @@
+/* ==========================================================================
+   Design System - Web Components
+   ========================================================================== */
+
+// TODO: aggregate and export the component subdirectories automatically.
+export * from './cfpb-button';
+export * from './cfpb-form-choice';
+export * from './cfpb-file-upload';
+export * from './cfpb-tag-filter';
+export * from './cfpb-tag-topic';
+export * from './cfpb-tag-group';

package/src/index.js

@@ -18,5 +18,4 @@ export * from './components/cfpb-typography';
 
 export * from './utilities';
 
-export * from './elements/cfpb-button';
-export * from './elements/cfpb-file-upload';
+export * from './elements';

package/src/utilities/utilities.scss

@@ -76,7 +76,7 @@
   // utility works as expected for screenreaders. Comma-separated syntax is
   // not used because space-separated is more backward-compatible,
   // per https://developer.mozilla.org/en-US/docs/Web/CSS/clip
-  clip: rect(0 0 0 0);
+  clip: rect(0 0 0 0); /* stylelint-disable-line property-no-deprecated */
 }
 
 .u-visually-hidden {