@cfpb/cfpb-design-system 4.0.4 → 4.1.0

package/src/elements/cfpb-multiselect/multiselect-model.js

@@ -0,0 +1,288 @@
+/**
+ *
+ * @element cfpb-multiselect.
+ * @slot - The main content for the upload button.
+ */
+export class MultiselectModel extends EventTarget {
+  // Declare private properties.
+  #options;
+  #name;
+  #max;
+  #optionsData;
+  #selectedIndices;
+  #filterIndicesList;
+  #lastFilterIndicesList;
+  #index;
+
+  // Undefined return value for void methods.
+  #UNDEFINED;
+
+  /**
+   * @class
+   * MultiselectModel
+   * @param {HTMLOptionsCollection} options
+   *   Set of options from a <select> element.
+   * @param {string} name - a unique name for this multiselect.
+   * @param {object} config - Customization of Multiselect behavior
+   */
+  constructor(options, name, config) {
+    super();
+
+    this.#options = options;
+    this.#name = name;
+    this.#max = config?.maxSelections || MultiselectModel.MAX_SELECTIONS;
+    this.#optionsData = [];
+
+    this.#selectedIndices = [];
+    this.#filterIndicesList = [];
+
+    /* When the options list is filtered, we store a list of filtered indices
+    so that when the filter changes we can reset the last matched options. */
+    this.#lastFilterIndicesList = [];
+
+    // Which option is in focus. -1 means the focus is on the search input.
+    this.#index = -1;
+  }
+
+  /**
+   * @param {HTMLElement} item - An option HTML node.
+   * @returns {string} A (hopefully) unique ID.
+   *   If it's not unique, we have a duplicate option value.
+   */
+  #getOptionId(item) {
+    return (
+      this.#name + '-' + item.value.trim().replace(/\s+/g, '-').toLowerCase()
+    );
+  }
+
+  /**
+   * @returns {boolean}
+   *   True if the maximum number of options are checked, false otherwise.
+   */
+  isAtMaxSelections() {
+    return this.#selectedIndices.length >= this.#max;
+  }
+
+  /**
+   * Cleans up a list of options for saving to memory.
+   * @param {HTMLOptionsCollection} list - The options from a select element.
+   * @returns {Array} An array of option objects.
+   */
+  #formatOptions(list) {
+    let item;
+    const cleaned = [];
+
+    let isChecked = false;
+    let isSelected = false;
+    for (let i = 0, len = list.length; i < len; i++) {
+      item = list[i];
+      isSelected = item.defaultSelected ? item.defaultSelected : false;
+      isChecked = this.isAtMaxSelections() ? false : isSelected;
+      cleaned.push({
+        id: this.#getOptionId(item),
+        value: item.value,
+        label: item.text,
+        text: item.text,
+        checked: isChecked,
+        index: i,
+      });
+
+      // If an option is initially checked, we need to record it.
+      if (isChecked) {
+        this.#selectedIndices.push(i);
+      }
+    }
+
+    return cleaned;
+  }
+
+  /**
+   * @returns {MultiselectModel} An instance.
+   */
+  init() {
+    this.#optionsData = this.#formatOptions(this.#options);
+
+    return this;
+  }
+
+  /**
+   * Toggle checked value of an option.
+   * @param {number} index - The index position of the option in the list.
+   * @returns {boolean} A value of true is checked and false is unchecked.
+   */
+  toggleOption(index) {
+    const isChecked = !this.#optionsData[index].checked;
+
+    if (isChecked && this.#selectedIndices.length < this.#max) {
+      this.#optionsData[index].checked = true;
+      this.#selectedIndices.push(index);
+      this.#selectedIndices.sort();
+
+      return true;
+    }
+
+    // We're over the max selections, reverse the check of the option.
+    this.#optionsData[index].checked = false;
+    this.#selectedIndices = this.#selectedIndices.filter(function (currIndex) {
+      return currIndex !== index;
+    });
+
+    return false;
+  }
+
+  /**
+   * Utility function for Array.reduce() used in searchIndices.
+   * @param {Array} aggregate - The reducer's accumulator.
+   * @param {object} item - Each item in the collection.
+   * @param {number} index - The index of item in the collection.
+   * @param {string} value - The value of item in the collection.
+   * @returns {Array} The reducer's accumulator.
+   */
+  #searchAggregator(aggregate, item, index, value) {
+    if (MultiselectModel.stringMatch(item.text, value)) {
+      aggregate.push(index);
+    }
+    return aggregate;
+  }
+
+  /**
+   * Search for a query string in the options text and return the indices of
+   * the matching positions in the options array.
+   * @param {string} query - A query string.
+   * @returns {Array} List of indices of the matching entries from the options.
+   */
+  filterIndices(query) {
+    // Convert query to a string if it's not.
+    if (Object.prototype.toString.call(query) !== '[object String]') {
+      query = '';
+    }
+
+    this.#lastFilterIndicesList = this.#filterIndicesList;
+
+    if (this.#optionsData.length > 0) {
+      this.#filterIndicesList = this.#optionsData.reduce((acc, item, index) => {
+        return this.#searchAggregator(acc, item, index, query);
+      }, []);
+    }
+
+    // Reset index position.
+    this.#index = -1;
+
+    return this.#filterIndicesList;
+  }
+
+  // This is used to search the items in the collection.
+  clearFilter() {
+    this.#filterIndicesList = this.#lastFilterIndicesList = [];
+    return this.#UNDEFINED;
+  }
+
+  get filterIndicesList() {
+    return this.#filterIndicesList;
+  }
+
+  get lastFilterIndicesList() {
+    return this.#lastFilterIndicesList;
+  }
+
+  // This is used to check an item in the collection.
+  get selectedIndices() {
+    return this.#selectedIndices;
+  }
+
+  /**
+   * Retrieve an option object from the options list.
+   * @param {number} index - The index position in the options list.
+   * @returns {object} The option object with text, value, and checked value.
+   */
+  getOption(index) {
+    return this.#optionsData[index];
+  }
+
+  /**
+   * Set the index of the collection (represents the highlighted option).
+   * @param {number} value - The index to set.
+   */
+  set index(value) {
+    const filterCount = this.#filterIndicesList.length;
+    const count = filterCount === 0 ? this.#optionsData.length : filterCount;
+    if (value < 0) {
+      this.#index = -1;
+    } else if (value >= count) {
+      this.#index = count - 1;
+    } else {
+      this.#index = value;
+    }
+  }
+
+  /**
+   * @returns {number} The current index (highlighted option).
+   */
+  get index() {
+    return this.#index;
+  }
+
+  resetIndex() {
+    this.#index = -1;
+    return this.#index;
+  }
+
+  get options() {
+    return this.#optionsData;
+  }
+
+  // These are used to highlight items in the collection.
+
+  /*
+
+  get items() {
+    console.log([...this.#items]);
+    return [...this.#items];
+  }
+
+  set items(newItems) {
+    this.#items = newItems;
+    this.#notify();
+  }
+
+  addItem(item) {
+    this.#items.push(item);
+    this.#notify();
+  }
+
+  removeItem(indexToRemove) {
+    this.#items.splice(indexToRemove, 1);
+  }
+
+  #notify() {
+    this.dispatchEvent(new Event('change'));
+  }
+
+  subscribe(callback) {
+    this.addEventListener('change', callback);
+    return () => this.removeEventListener('change', callback);
+  }
+  */
+
+  // How many options may be checked.
+  static MAX_SELECTIONS = 5;
+
+  /**
+   * Escapes a string.
+   * @param {string} str - The string to escape.
+   * @returns {string} The escaped string.
+   */
+  static stringEscape(str) {
+    return str.replace(/[-\\^$*+?.()|[\]{}]/g, '\\$&');
+  }
+
+  /**
+   * Tests whether a string matches another.
+   * @param   {string}  x - The control string.
+   * @param   {string}  y - The comparison string.
+   * @returns {boolean}   True if `x` and `y` match, false otherwise.
+   */
+  static stringMatch(x, y) {
+    return RegExp(MultiselectModel.stringEscape(y.trim()), 'i').test(x);
+  }
+}

package/src/elements/cfpb-multiselect/multiselect-model.spec.js

@@ -0,0 +1,236 @@
+import { MultiselectModel } from './multiselect-model.js';
+
+const HTML_SNIPPET = `
+<select class="o-multiselect" multiple>
+  <option value="mortgages">
+    Mortgages
+  </option>
+  <option value="financial-education" selected>
+    Financial education
+  </option>
+  <option value="financial-well-being">
+    Financial well-being
+  </option>
+  <option value="student-loans">
+    Student loans
+  </option>
+  <option value="rulemaking">
+    Rulemaking
+  </option>
+  <option value="banking">
+    Banking
+  </option>
+</select>
+`;
+
+let multiselectModel;
+let selectDom;
+
+describe('MultiselectModel', () => {
+  beforeEach(() => {
+    document.body.innerHTML = HTML_SNIPPET;
+
+    selectDom = document.querySelector('select[multiple]');
+    multiselectModel = new MultiselectModel(selectDom.options).init();
+  });
+
+  describe('init()', () => {
+    it('should correctly initialize when given valid options', () => {
+      multiselectModel = new MultiselectModel(selectDom.options).init();
+      expect(multiselectModel.constructor).toBe(MultiselectModel);
+    });
+  });
+
+  describe('toggleOption()', () => {
+    it('should toggle checked value of option', () => {
+      expect(multiselectModel.getOption(0).checked).toBe(false);
+      expect(multiselectModel.toggleOption(0)).toBe(true);
+      expect(multiselectModel.getOption(0).checked).toBe(true);
+
+      expect(multiselectModel.getOption(1).checked).toBe(true);
+      expect(multiselectModel.toggleOption(1)).toBe(false);
+      expect(multiselectModel.getOption(1).checked).toBe(false);
+
+      expect(multiselectModel.getOption(2).checked).toBe(false);
+      expect(multiselectModel.toggleOption(2)).toBe(true);
+      expect(multiselectModel.getOption(2).checked).toBe(true);
+
+      expect(multiselectModel.getOption(3).checked).toBe(false);
+      expect(multiselectModel.toggleOption(3)).toBe(true);
+      expect(multiselectModel.getOption(3).checked).toBe(true);
+
+      expect(multiselectModel.getOption(4).checked).toBe(false);
+      expect(multiselectModel.toggleOption(4)).toBe(true);
+      expect(multiselectModel.getOption(4).checked).toBe(true);
+
+      expect(multiselectModel.getOption(5).checked).toBe(false);
+      expect(multiselectModel.toggleOption(5)).toBe(true);
+      expect(multiselectModel.getOption(5).checked).toBe(true);
+
+      // Try to push beyond maximum selections.
+      expect(multiselectModel.toggleOption(1)).toBe(false);
+      expect(multiselectModel.getOption(1).checked).toBe(false);
+      expect(multiselectModel.toggleOption(2)).toBe(false);
+      expect(multiselectModel.getOption(2).checked).toBe(false);
+      expect(multiselectModel.toggleOption(1)).toBe(true);
+      expect(multiselectModel.getOption(1).checked).toBe(true);
+    });
+  });
+
+  describe('getSelectedIndices()', () => {
+    it('should get the indices of the checked options', () => {
+      expect(multiselectModel.selectedIndices[0]).toBe(1);
+      multiselectModel.toggleOption(0);
+      expect(multiselectModel.selectedIndices[0]).toBe(0);
+      expect(multiselectModel.selectedIndices[1]).toBe(1);
+    });
+  });
+
+  describe('isAtMaxSelections()', () => {
+    it('should toggle checked value of option', () => {
+      expect(multiselectModel.isAtMaxSelections()).toBe(false);
+
+      multiselectModel.toggleOption(0);
+      expect(multiselectModel.isAtMaxSelections()).toBe(false);
+
+      // No need to toggle the second option because it's already checked.
+
+      multiselectModel.toggleOption(2);
+      expect(multiselectModel.isAtMaxSelections()).toBe(false);
+
+      multiselectModel.toggleOption(3);
+      expect(multiselectModel.isAtMaxSelections()).toBe(false);
+
+      multiselectModel.toggleOption(4);
+      expect(multiselectModel.isAtMaxSelections()).toBe(true);
+
+      multiselectModel.toggleOption(5);
+      expect(multiselectModel.isAtMaxSelections()).toBe(true);
+
+      multiselectModel.toggleOption(5);
+      expect(multiselectModel.isAtMaxSelections()).toBe(true);
+
+      expect(multiselectModel.toggleOption(4)).toBe(false);
+      expect(multiselectModel.isAtMaxSelections()).toBe(false);
+    });
+  });
+
+  describe('filterIndices()', () => {
+    it('should return indices of matched options in a search', () => {
+      expect(multiselectModel.filterIndices('mo').length).toBe(1);
+      expect(multiselectModel.filterIndices('mort').length).toBe(1);
+      expect(multiselectModel.filterIndices('mort')[0]).toBe(0);
+      expect(multiselectModel.filterIndices('fin').length).toBe(2);
+      expect(multiselectModel.filterIndices('fin')[0]).toBe(1);
+      expect(multiselectModel.filterIndices('fin')[1]).toBe(2);
+      expect(multiselectModel.filterIndices('being').length).toBe(1);
+      expect(multiselectModel.filterIndices('being')[0]).toBe(2);
+      expect(multiselectModel.filterIndices('').length).toBe(6);
+      expect(multiselectModel.filterIndices().length).toBe(6);
+      expect(multiselectModel.filterIndices([]).length).toBe(6);
+      expect(multiselectModel.filterIndices({}).length).toBe(6);
+    });
+  });
+
+  describe('clearFilter()', () => {
+    it('should clear current and last matched options in a search', () => {
+      multiselectModel.filterIndices('fin');
+      expect(multiselectModel.lastFilterIndicesList.length).toBe(0);
+      expect(multiselectModel.filterIndicesList.length).toBe(2);
+      multiselectModel.filterIndices('mo');
+      expect(multiselectModel.lastFilterIndicesList.length).toBe(2);
+      expect(multiselectModel.filterIndicesList.length).toBe(1);
+      multiselectModel.clearFilter();
+      expect(multiselectModel.lastFilterIndicesList.length).toBe(0);
+      expect(multiselectModel.filterIndicesList.length).toBe(0);
+    });
+  });
+
+  describe('getFilterIndices()', () => {
+    it('should return current indices of matched options in a search', () => {
+      expect(multiselectModel.filterIndicesList.length).toBe(0);
+      multiselectModel.filterIndices('fin');
+      expect(multiselectModel.filterIndicesList.length).toBe(2);
+      expect(multiselectModel.filterIndicesList[0]).toBe(1);
+      expect(multiselectModel.filterIndicesList[1]).toBe(2);
+    });
+  });
+
+  describe('getLastFilterIndices()', () => {
+    it('should return indices of the last matched options in a search', () => {
+      expect(multiselectModel.lastFilterIndicesList.length).toBe(0);
+      multiselectModel.filterIndices('fin');
+      expect(multiselectModel.lastFilterIndicesList.length).toBe(0);
+      multiselectModel.filterIndices('mo');
+      expect(multiselectModel.lastFilterIndicesList.length).toBe(2);
+      expect(multiselectModel.lastFilterIndicesList[0]).toBe(1);
+      expect(multiselectModel.lastFilterIndicesList[1]).toBe(2);
+      multiselectModel.filterIndices('being');
+      expect(multiselectModel.lastFilterIndicesList.length).toBe(1);
+      expect(multiselectModel.lastFilterIndicesList[0]).toBe(0);
+    });
+  });
+
+  describe('getIndex()', () => {
+    it('should get correct index when no filter results', () => {
+      expect(multiselectModel.index).toBe(-1);
+      multiselectModel.index = 2;
+      expect(multiselectModel.index).toBe(2);
+      multiselectModel.filterIndices('asdf');
+      expect(multiselectModel.index).toBe(-1);
+    });
+
+    it('should get reset index when options are filtered', () => {
+      expect(multiselectModel.index).toBe(-1);
+      multiselectModel.index = 2;
+      expect(multiselectModel.index).toBe(2);
+      multiselectModel.filterIndices('mo');
+      expect(multiselectModel.index).toBe(-1);
+    });
+  });
+
+  describe('setIndex()', () => {
+    it('should set index within available option range', () => {
+      expect(multiselectModel.index).toBe(-1);
+      multiselectModel.index = 0;
+      expect(multiselectModel.index).toBe(0);
+      multiselectModel.index = 1;
+      expect(multiselectModel.index).toBe(1);
+      multiselectModel.index = 2;
+      expect(multiselectModel.index).toBe(2);
+      multiselectModel.index = 10;
+      expect(multiselectModel.index).toBe(5);
+      multiselectModel.index = -2;
+      expect(multiselectModel.index).toBe(-1);
+    });
+
+    it('should set index within filtered option range', () => {
+      expect(multiselectModel.index).toBe(-1);
+      multiselectModel.filterIndices('fin');
+      multiselectModel.index = 0;
+      expect(multiselectModel.index).toBe(0);
+      expect(multiselectModel.filterIndicesList[multiselectModel.index]).toBe(
+        1,
+      );
+      multiselectModel.index = 1;
+      expect(multiselectModel.index).toBe(1);
+      multiselectModel.index = 2;
+      expect(multiselectModel.index).toBe(1);
+    });
+  });
+
+  describe('resetIndex()', () => {
+    it('should return -1 for index when called', () => {
+      expect(multiselectModel.resetIndex()).toBe(-1);
+    });
+  });
+
+  describe('getOption()', () => {
+    it('should return the correct option when requested', () => {
+      expect(multiselectModel.getOption(2).text).toBe('Financial well-being');
+      expect(multiselectModel.getOption(2).value).toBe('financial-well-being');
+      expect(multiselectModel.getOption(2).checked).toBe(false);
+      expect(multiselectModel.getOption(1).checked).toBe(true);
+    });
+  });
+});

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

@@ -14,7 +14,7 @@ export class CfpbTagFilter extends LitElement {
   `;
 
   /**
-   * @property {string} for - Whether to stack the tags vertically.
+   * @property {string} for - Associate the label with an ID elsewhere.
    */
   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/index.js

@@ -23,6 +23,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/index.js

@@ -6,6 +6,8 @@
 export * from './cfpb-button';
 export * from './cfpb-form-choice';
 export * from './cfpb-file-upload';
+export * from './cfpb-label';
 export * from './cfpb-tag-filter';
 export * from './cfpb-tag-topic';
 export * from './cfpb-tag-group';
+export * from './cfpb-multiselect';