@cfpb/cfpb-design-system 4.2.4 → 4.3.1

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

@@ -0,0 +1,379 @@
+import { LitElement, html, css, unsafeCSS } from 'lit';
+import { ref, createRef } from 'lit/directives/ref.js';
+import styles from './cfpb-list.component.scss';
+import { CfpbListItem } from '../cfpb-list-item';
+import { parseChildData } from '../cfpb-utilities/parse-child-data';
+
+export class CfpbList extends LitElement {
+  static styles = css`
+    ${unsafeCSS(styles)}
+  `;
+
+  #internalSync = false;
+  #container = createRef();
+  #items = [];
+  #checkedItems = [];
+  #visibleItems = [];
+
+  // index in visibleItems
+  #focusedIndex = -1;
+
+  // WeakMap to store per-item click listeners.
+  #clickListeners = new WeakMap();
+
+  /**
+   * @property {Array} childData - Structure data to create child components.
+   * @property {boolean} multiple - Whether the select supports multiple or not.
+   * @property {string} type - List item type: plain, check, or checkbox.
+   * @property {string} ariaLabel - The aria-label for the list container.
+   * @returns {object} The map of properties.
+   */
+  static properties = {
+    childData: { type: Array, attribute: 'childdata' },
+    multiple: { type: Boolean, reflect: true },
+    type: { type: String, reflect: true },
+    ariaLabel: { type: String, attribute: 'aria-label' },
+  };
+
+  constructor() {
+    super();
+    this.childData = '';
+    this.multiple = false;
+    this.type = 'plain';
+    this.ariaLabel = '';
+  }
+
+  firstUpdated() {
+    this.#syncItems();
+  }
+
+  updated(changedProps) {
+    if (!this.#internalSync && changedProps.has('childData')) {
+      const parsed = parseChildData(this.childData);
+      if (parsed) this.#renderItemsFromData(parsed);
+    }
+    if (changedProps.has('type')) {
+      this.#applyTypeToItems();
+    }
+  }
+
+  // -------------------------
+  // ITEMS ACCESS
+  // -------------------------
+  get items() {
+    return this.#items;
+  }
+  get checkedItems() {
+    return this.#checkedItems;
+  }
+  get visibleItems() {
+    return this.#visibleItems;
+  }
+  get visibleCheckedItems() {
+    return this.#visibleItems.filter((item) => item.checked);
+  }
+
+  // -------------------------
+  // RENDER ITEMS
+  // -------------------------
+  #renderItemsFromData(itemsArray) {
+    [...this.children].forEach((child) => {
+      if (child.tagName !== 'TEMPLATE' && child.tagName !== 'NOSCRIPT')
+        child.remove();
+    });
+
+    let firstChecked = null;
+    itemsArray.forEach((data) => {
+      const item = document.createElement('cfpb-list-item');
+      item.textContent = data.value ?? '';
+      if ('disabled' in data) item.disabled = data.disabled;
+      if ('hidden' in data) item.hidden = data.hidden;
+      if ('href' in data) item.href = data.href;
+      item.type = data.type ?? this.type;
+
+      if (this.multiple) {
+        if ('checked' in data) item.checked = data.checked;
+      } else if (!firstChecked && data.checked) {
+        firstChecked = item;
+        item.checked = true;
+      }
+
+      this.appendChild(item);
+    });
+
+    this.#syncItems();
+  }
+
+  // -------------------------
+  // SYNC ITEMS & LISTENERS
+  // -------------------------
+  #syncItems() {
+    // Collect items.
+    this.#items = [...this.querySelectorAll('cfpb-list-item')];
+
+    // Ensure each item has a type.
+    this.#items.forEach((item) => {
+      if (!item.type) item.type = this.type;
+    });
+
+    // Visible items.
+    this.#visibleItems = this.#items.filter((item) => !item.hidden);
+
+    // Populate initial checked states.
+    if (this.multiple) {
+      this.#checkedItems = this.#items.filter((item) => item.checked);
+    } else {
+      const firstChecked = this.#items.find((item) => item.checked);
+      this.#checkedItems = firstChecked ? [firstChecked] : [];
+
+      // Uncheck all others.
+      this.#items.forEach((item) => {
+        if (item !== firstChecked) item.checked = false;
+      });
+    }
+
+    // Assign tabindex, role, listeners.
+    this.#items.forEach((item, index) => {
+      item.setAttribute('tabindex', '-1');
+      item.setAttribute('role', 'option');
+
+      // Remove prior listener if present.
+      const prev = this.#clickListeners.get(item);
+      if (prev) item.removeEventListener('click-item', prev);
+
+      // Listener that toggles the item before handling.
+      const listener = (evt) => {
+        // Prevent actual click bubbling to list container.
+        evt.stopPropagation();
+        this.#handleToggle(item, item.checked, index);
+      };
+
+      item.addEventListener('click-item', listener);
+      this.#clickListeners.set(item, listener);
+
+      // Track focus index.
+      item.addEventListener('focus', () => {
+        const visIndex = this.#visibleItems.indexOf(item);
+        if (visIndex !== -1) this.#focusedIndex = visIndex;
+      });
+    });
+
+    this.dispatchEvent(
+      new CustomEvent('items-ready', {
+        detail: {
+          items: this.#items,
+          checkedItems: this.#checkedItems,
+          visibleItems: this.#visibleItems,
+          visibleCheckedItems: this.visibleCheckedItems,
+        },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  #syncChildDataFromItems() {
+    const data = this.#items.map((item) => ({
+      value: item.value,
+      label: item.textContent.trim(),
+      checked: item.checked,
+      disabled: item.disabled,
+    }));
+    this.#internalSync = true;
+    this.childData = data;
+    this.#internalSync = false;
+  }
+
+  #applyTypeToItems() {
+    if (!['plain', 'check', 'checkbox'].includes(this.type)) {
+      console.warn(`<cfpb-list>: invalid type "${this.type}".`);
+      return;
+    }
+    this.#items.forEach((item) => (item.type = this.type));
+  }
+
+  #handleToggle(element, isChecked, index) {
+    if (this.multiple) {
+      if (isChecked) {
+        // Add if not already present.
+        if (!this.#checkedItems.includes(element))
+          this.#checkedItems.push(element);
+      } else {
+        // Remove cleanly.
+        this.#checkedItems = this.#checkedItems.filter(
+          (item) => item !== element,
+        );
+      }
+    } else {
+      if (isChecked) {
+        // Select this item, uncheck all others.
+        this.#items.forEach((item) => {
+          if (item !== element) item.checked = false;
+        });
+        this.#checkedItems = [element];
+      } else {
+        // Item is unchecked -> clear selection.
+        this.#checkedItems.forEach((item) => (item.checked = false));
+        this.#checkedItems = [];
+      }
+    }
+
+    this.#syncChildDataFromItems();
+
+    window.queueMicrotask(() => {
+      const visIndex = this.#visibleItems.indexOf(element);
+      this.focusItemAt(visIndex !== -1 ? visIndex : -1);
+    });
+
+    this.dispatchEvent(
+      new CustomEvent('item-click', {
+        detail: { index, value: element.value, element },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  // -------------------------
+  // FILTER & FOCUS
+  // -------------------------
+
+  /**
+   * @param {Array} queryList - List of search words.
+   * @returns {Array} List of visible list items.
+   */
+  filterItems(queryList) {
+    this.#visibleItems = [];
+    let firstVisibleIndex = -1;
+
+    this.#items.forEach((item) => {
+      const matches = queryList.some((q) =>
+        item.value.toLowerCase().includes(q.toLowerCase()),
+      );
+      item.hidden = !matches;
+      if (matches) {
+        if (firstVisibleIndex === -1)
+          firstVisibleIndex = this.#visibleItems.length;
+        this.#visibleItems.push(item);
+      }
+    });
+
+    this.#focusedIndex = firstVisibleIndex;
+    this.#broadcastFiltered();
+
+    return this.#visibleItems;
+  }
+
+  showAllItems() {
+    this.#items.forEach((item) => (item.hidden = false));
+    this.#visibleItems = [...this.#items];
+    this.#focusedIndex = 0;
+    this.#broadcastFiltered();
+  }
+
+  #broadcastFiltered() {
+    this.dispatchEvent(
+      new CustomEvent('items-filter', {
+        detail: {
+          items: this.#items,
+          checkedItems: this.#checkedItems,
+          visibleItems: this.#visibleItems,
+          visibleCheckedItems: this.visibleCheckedItems,
+        },
+        bubbles: true,
+        composed: true,
+      }),
+    );
+  }
+
+  #focusContainer() {
+    this.#container.value.focus();
+    this.#focusedIndex = -1;
+  }
+
+  /**
+   * Focus a visible item by index.
+   * Pass -1 to move focus to the list container (no active item).
+   * @param {number} index - The index of the item to focus.
+   * @returns {undefined} If nothing to focus.
+   */
+  focusItemAt(index) {
+    // No active item (sentinel or invalid input).
+    const visibleItems = this.#visibleItems;
+    if (
+      !visibleItems.length ||
+      index == null ||
+      typeof index !== 'number' ||
+      Number.isNaN(index) ||
+      index === -1
+    ) {
+      this.#focusContainer();
+      return;
+    }
+
+    const normalizedIndex =
+      ((index % visibleItems.length) + visibleItems.length) %
+      visibleItems.length;
+    visibleItems[normalizedIndex].focus();
+    this.#focusedIndex = normalizedIndex;
+  }
+
+  #onFocus(evt) {
+    // If the focus is on the container itself (not an item), set index to -1.
+    if (evt.target === this.#container.value) this.#focusContainer();
+  }
+
+  #onKeyDown(evt) {
+    const visibleItems = this.#visibleItems;
+    if (!visibleItems.length) return;
+    const last = visibleItems.length - 1;
+
+    switch (evt.key) {
+      case 'ArrowDown':
+        evt.preventDefault();
+        this.focusItemAt(this.#focusedIndex < 0 ? 0 : this.#focusedIndex + 1);
+        break;
+      case 'ArrowUp':
+        evt.preventDefault();
+        this.focusItemAt(
+          this.#focusedIndex < 0 ? last : this.#focusedIndex - 1,
+        );
+        break;
+      case 'Home':
+        evt.preventDefault();
+        this.focusItemAt(0);
+        break;
+      case 'End':
+        evt.preventDefault();
+        this.focusItemAt(last);
+        break;
+    }
+  }
+
+  get focusedIndex() {
+    return this.#focusedIndex;
+  }
+
+  render() {
+    return html`
+      <div
+        role="listbox"
+        tabindex="0"
+        @keydown=${this.#onKeyDown}
+        @focus=${this.#onFocus}
+        aria-label=${this.ariaLabel}
+        ?aria-multiselectable=${this.multiple}
+        ${ref(this.#container)}
+      >
+        <slot></slot>
+      </div>
+    `;
+  }
+
+  static init() {
+    CfpbListItem.init();
+    if (!window.customElements.get('cfpb-list')) {
+      window.customElements.define('cfpb-list', CfpbList);
+    }
+  }
+}

package/src/elements/cfpb-list/index.spec.js

@@ -0,0 +1,214 @@
+import { jest } from '@jest/globals';
+import { CfpbList } from './index';
+
+beforeAll(() => {
+  CfpbList.init();
+});
+
+describe('<cfpb-list> tests', () => {
+  let list;
+
+  beforeEach(() => {
+    list = document.createElement('cfpb-list');
+    document.body.appendChild(list);
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  test('renders childData and sets checked state (single)', async () => {
+    list.childData = JSON.stringify([
+      { value: 'A', checked: true },
+      { value: 'B', checked: true },
+      { value: 'C' },
+    ]);
+
+    await list.updateComplete;
+
+    expect(list.items.length).toBe(3);
+    expect(list.items[0].checked).toBe(true);
+    expect(list.items[1].checked).toBe(false);
+    expect(list.items[2].checked).toBe(false);
+    expect(list.checkedItems).toEqual([list.items[0]]);
+  });
+
+  test('multiple selection mode allows multiple checked items', async () => {
+    list.multiple = true;
+    list.childData = JSON.stringify([
+      { value: 'A', checked: true },
+      { value: 'B', checked: true },
+      { value: 'C' },
+    ]);
+
+    await list.updateComplete;
+
+    expect(list.checkedItems.length).toBe(2);
+    expect(list.checkedItems).toContain(list.items[0]);
+    expect(list.checkedItems).toContain(list.items[1]);
+
+    const event = new CustomEvent('click-item', {
+      bubbles: true,
+      composed: true,
+    });
+    list.items[0].checked = false;
+    list.items[0].dispatchEvent(event);
+
+    expect(list.checkedItems).toEqual([list.items[1]]);
+  });
+
+  test('click-item toggles single selection', async () => {
+    list.childData = JSON.stringify([{ value: 'A' }, { value: 'B' }]);
+    await list.updateComplete;
+
+    const clickSpy = jest.fn();
+    list.addEventListener('item-click', clickSpy);
+
+    list.items[0].checked = true;
+    list.items[0].dispatchEvent(
+      new CustomEvent('click-item', { bubbles: true, composed: true }),
+    );
+
+    expect(list.checkedItems).toEqual([list.items[0]]);
+    expect(clickSpy).toHaveBeenCalledTimes(1);
+
+    list.items[0].checked = false;
+    list.items[0].dispatchEvent(
+      new CustomEvent('click-item', { bubbles: true, composed: true }),
+    );
+    expect(list.checkedItems).toEqual([]);
+  });
+
+  test('replaces prior click listeners on items', async () => {
+    list.childData = JSON.stringify([{ value: 'X' }]);
+    await list.updateComplete;
+
+    const listenerSpy = jest.fn();
+    list.addEventListener('item-click', listenerSpy);
+
+    const event = new CustomEvent('click-item', {
+      bubbles: true,
+      composed: true,
+    });
+    list.items[0].dispatchEvent(event);
+
+    expect(listenerSpy).toHaveBeenCalled();
+  });
+
+  test('filterItems hides items and sets focused index', async () => {
+    list.childData = JSON.stringify([
+      { value: 'A' },
+      { value: 'B' },
+      { value: 'C' },
+    ]);
+    await list.updateComplete;
+
+    list.filterItems(['B']);
+    expect(list.visibleItems.length).toBe(1);
+    expect(list.visibleItems[0].value).toBe('B');
+    expect(list.items[0].hidden).toBe(true);
+    expect(list.items[1].hidden).toBe(false);
+    expect(list.items[2].hidden).toBe(true);
+  });
+
+  test('arrow keys skip hidden items', async () => {
+    list.childData = JSON.stringify([
+      { value: 'A' },
+      { value: 'B' },
+      { value: 'C' },
+    ]);
+    await list.updateComplete;
+
+    list.filterItems(['C']); // only C visible
+
+    const container = list.shadowRoot.querySelector('div');
+    container.focus();
+    expect(document.activeElement.tagName).toBe('CFPB-LIST');
+
+    // ArrowDown → first visible
+    container.dispatchEvent(
+      new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }),
+    );
+    expect(document.activeElement.value).toBe('C');
+
+    // ArrowDown → wrap
+    container.dispatchEvent(
+      new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }),
+    );
+    expect(document.activeElement.value).toBe('C');
+
+    // ArrowUp → wrap
+    container.dispatchEvent(
+      new KeyboardEvent('keydown', { key: 'ArrowUp', bubbles: true }),
+    );
+    expect(document.activeElement.tagName).toBe('CFPB-LIST');
+  });
+
+  test('showAllItems unhides all items', async () => {
+    list.childData = JSON.stringify([
+      { value: 'A', hidden: true },
+      { value: 'B', hidden: true },
+    ]);
+    await list.updateComplete;
+
+    list.showAllItems();
+    expect(list.items.every((i) => i.hidden === false)).toBe(true);
+    expect(list.visibleItems.length).toBe(2);
+  });
+
+  test('invalid childData logs error', async () => {
+    console.error = jest.fn();
+    list.childData = 'not-json';
+    await list.updateComplete;
+    expect(console.error).toHaveBeenCalled();
+  });
+
+  // -------------------------------
+  // focusItemAt sentinel tests
+  // -------------------------------
+
+  test('focusItemAt(-1) focuses the container', async () => {
+    list.childData = JSON.stringify([{ value: 'A' }, { value: 'B' }]);
+    await list.updateComplete;
+    list.focusItemAt(-1);
+    expect(document.activeElement.tagName).toBe('CFPB-LIST');
+  });
+
+  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');
+  });
+
+  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');
+  });
+
+  test('ArrowDown from container focuses first visible item', async () => {
+    list.childData = JSON.stringify([{ value: 'A' }, { value: 'B' }]);
+    await list.updateComplete;
+
+    const container = list.shadowRoot.querySelector('div');
+    container.focus();
+    container.dispatchEvent(
+      new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }),
+    );
+    expect(document.activeElement.value).toBe('A');
+  });
+
+  test('ArrowUp from container focuses last visible item', async () => {
+    list.childData = JSON.stringify([{ value: 'A' }, { value: 'B' }]);
+    await list.updateComplete;
+
+    const container = list.shadowRoot.querySelector('div');
+    container.focus();
+    container.dispatchEvent(
+      new KeyboardEvent('keydown', { key: 'ArrowUp', bubbles: true }),
+    );
+    expect(document.activeElement.value).toBe('B');
+  });
+});

package/src/elements/cfpb-list-item/cfpb-list-item.component.scss

@@ -0,0 +1,69 @@
+@use 'sass:math';
+@use '@cfpb/cfpb-design-system/src/elements/abstracts' as *;
+
+:host {
+  // Theme variables.
+  --list-item-bg-hover: var(--gray-5);
+  --list-item-border-focus: var(--pacific);
+
+  display: block;
+
+  .container {
+    display: block;
+    padding: 6.5px 10px;
+  }
+
+  .checkbox {
+    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;
+    vertical-align: top;
+
+    // Wrap long words in narrow form fields to prevent clipping
+    overflow-wrap: anywhere;
+  }
+
+  .selectable {
+    cursor: pointer;
+
+    &:hover {
+      background: var(--list-item-bg-hover);
+      transition: background-color 0.2s;
+      cursor: pointer;
+    }
+  }
+}
+
+// Remove default focus ring.
+:host(:focus) {
+  outline: none;
+}
+
+// Add custom focus ring.
+:host(:not([disabled]):focus-within) {
+  outline: 1px dotted var(--list-item-border-focus);
+  outline-offset: 2px;
+}
+
+:host([checked]) {
+  .checkbox::before {
+    --cfpb-background-icon-svg: 'approved';
+
+    background-size: auto $cf-icon-height;
+    background-repeat: no-repeat;
+    background-position: center 0;
+  }
+}
+
+:host([type='plain']) {
+  .checkbox::before {
+    border-color: transparent;
+    outline-color: transparent;
+    background-color: transparent;
+  }
+}
+
+:host([hidden]) {
+  display: none;
+}