@madgex/design-system 13.4.0 → 13.5.1

package/src/components/inputs/category-picker/README.md

@@ -0,0 +1,45 @@
+## Category Picker (Tags with Combobox)
+
+A tags-with-combobox control: an input-like wrapper displays selected items as removable pills. Clicking or focusing the input reveals a dropdown containing a checkbox-list. Typing 2+ characters filters the visible options.
+
+### Parameters — Nunjucks
+
+- `removeButtonAria`: Base aria-label for pill remove buttons. Defaults to `'remove category'`. The pill's path text is appended.
+- `searchPlaceholder`: Placeholder text for the search input. Defaults to `'Search or select…'`.
+- `checkboxList`: Passes parameters through to the checkbox-list component. See checkbox-list README.
+- `i18n.selectedTermsLabel`: Visually hidden label for the pill list. Defaults to `'Selected terms:'`.
+- `i18n.noResults`: Message shown when search filter finds no matches. Defaults to `'No matching options'`.
+- `i18n.optionsSelectedSingular`: Announcement when 1 option is selected. Defaults to `'1 option selected'`.
+- `i18n.optionsSelectedPlural`: Announcement when multiple options are selected. Use `{count}` placeholder. Defaults to `'{count} options selected'`.
+- `i18n.optionsFoundSingular`: Announcement when 1 option matches the filter. Defaults to `'1 option found'`.
+- `i18n.optionsFoundPlural`: Announcement when multiple options match the filter. Use `{count}` placeholder. Defaults to `'{count} options found'`.
+
+### Behaviour
+
+- **Click / focus input** → dropdown opens with checkbox-list
+- **Check a checkbox** → pill appears in the input, search clears, dropdown stays open
+- **Click pill ✕ / uncheck checkbox** → pill removed
+- **Type 2+ characters** → options filtered by label text (case-insensitive); parent groups auto-expand to show matches; if a parent label matches, all its children are shown
+- **Backspace on empty input** → removes last pill
+- **Escape** → closes dropdown and clears search (works from search input or within dropdown)
+- **ArrowDown** → moves focus from input into the first visible checkbox
+- **Tab** → closes dropdown and moves to next form field
+- **Click outside** → closes dropdown
+
+### Accessibility
+
+- Search input has `role="combobox"`, `aria-expanded`, `aria-controls`, `aria-autocomplete="list"`, `aria-haspopup="dialog"`
+- Dropdown has `role="dialog"` with `aria-label` from the checkbox-list label
+- Real `<input type="checkbox">` elements inside dropdown for native checked/unchecked announcements
+- `aria-live="polite"` region announces filter result count and selection changes
+- Pill remove buttons have `aria-label="remove category {path}"`
+- Visually hidden "Selected terms:" label introduces the pill list for screen readers
+- Pills are rendered as a list (`ul`/`li`) for semantic structure
+
+### Progressive Enhancement
+
+Without JS the checkbox-list renders normally (visible, no dropdown, no pills). The custom element upgrades the markup when JS is available.
+
+### Note
+
+The JS, especially for finding the input hierarchy, is highly dependent on checkbox-list and should be updated with it if any changes are made.

package/src/components/inputs/category-picker/_macro.njk

@@ -0,0 +1,3 @@
+{% macro MdsCategoryPicker(params) %}
+    {%- include "./_template.njk" -%}
+{% endmacro %}

package/src/components/inputs/category-picker/_template.njk

@@ -0,0 +1,83 @@
+{% from "../checkbox-list/_macro.njk" import MdsCheckboxList %}
+{% from "../label/_macro.njk" import MdsInputLabel %}
+{% from "../_message/_macro.njk" import MdsInputMessages %}
+{% from "../../icons/_macro.njk" import MdsIcon %}
+
+{%- if params.checkboxList -%}
+  {%- set pickerI18n = params.i18n or {} -%}
+  {%- set pickerId = params.checkboxList.id | default('category-picker') -%}
+  {%- set dropdownId = pickerId ~ '-dropdown' -%}
+  {%- set searchId = pickerId ~ '-search' -%}
+
+  {% if params.checkboxList.helpText %}
+    {% set helpTextId = [pickerId, '-help-text'] | join %}
+  {% endif %}
+  {% if params.checkboxList.validationError %}
+    {% set validationErrorId = [pickerId, '-validation-error'] | join %}
+  {% endif %}
+  {% if helpTextId or validationErrorId or params.checkboxList.describedBy %}
+    {% set ariaDescribedBy = [validationErrorId, helpTextId, params.checkboxList.describedBy] | join(' ') | trim %}
+  {% endif %}
+
+  <div class="mds-form-element{% if params.checkboxList.state %} mds-form-element--{{ params.checkboxList.state }}{% endif %}">
+    {{ MdsInputLabel({
+      labelText: params.checkboxList.labelText,
+      hideLabel: params.checkboxList.hideLabel,
+      inputId: searchId,
+      optional: params.checkboxList.optional,
+      tooltipMessage: params.checkboxList.tooltipMessage,
+      i18n: params.checkboxList.i18n
+    }) }}
+    {{ MdsInputMessages({
+      id: pickerId,
+      helpTextId: helpTextId,
+      helpText: params.checkboxList.helpText,
+      validationErrorId: validationErrorId,
+      validationError: params.checkboxList.validationError
+    }) }}
+
+    <mds-category-picker i18n="{{ pickerI18n | dump }}">
+      <span class="mds-category-picker__templates">{# Removed with JS on load #}
+        <ul><li class="mds-category-picker__pill mds-border"></li></ul>
+        <button class="mds-category-picker__clear-pill" type="button" aria-label="{{ params.removeButtonAria | default('remove category') }}">{{- MdsIcon({ iconName: 'close' }) -}}</button>
+      </span>
+
+      <div class="mds-category-picker__input-wrapper">
+        <span class="mds-visually-hidden">{{ pickerI18n.selectedTermsLabel | default('Selected terms:') }}</span>
+        <ul class="mds-category-picker__pillbox" role="list">{# Pills added with JS #}</ul>
+        <input
+          class="mds-category-picker__search"
+          id="{{ searchId }}"
+          type="text"
+          role="combobox"
+          autocomplete="off"
+          aria-expanded="false"
+          aria-controls="{{ dropdownId }}"
+          aria-autocomplete="list"
+          aria-haspopup="dialog"
+          placeholder="{{ params.searchPlaceholder | default('Search or select…') }}"
+          {% if ariaDescribedBy %}aria-describedby="{{ ariaDescribedBy }}"{% endif %}
+        />
+      </div>
+
+      <div id="{{ dropdownId }}" class="mds-category-picker__dropdown" role="dialog" aria-label="{{ params.checkboxList.labelText | default('Options') }}">
+        {# Hide the checkbox-list's built-in legend since we render the label above #}
+        {{- MdsCheckboxList({
+          labelText: params.checkboxList.labelText,
+          hideLabel: true,
+          id: params.checkboxList.id,
+          name: params.checkboxList.name,
+          options: params.checkboxList.options,
+          selectedOptions: params.checkboxList.selectedOptions,
+          disabled: params.checkboxList.disabled,
+          containerClasses: params.checkboxList.containerClasses,
+          i18n: params.checkboxList.i18n,
+          describedBy: params.checkboxList.describedBy
+        }) -}}
+        <div class="mds-category-picker__no-results">{{ pickerI18n.noResults | default('No matching options') }}</div>
+      </div>
+
+      <div class="mds-category-picker__live-region mds-visually-hidden" aria-live="polite" aria-atomic="true"></div>
+    </mds-category-picker>
+  </div>
+{%- endif -%}

package/src/components/inputs/category-picker/category-picker.config.js

@@ -0,0 +1,176 @@
+const options = [
+  {
+    value: 101,
+    labelText: 'Arts & heritage',
+    options: [
+      { value: 600102, labelText: 'Artist agency & management', options: [] },
+      { value: 600104, labelText: 'Arts education & training', options: [] },
+      {
+        value: 123,
+        labelText: 'Art sales',
+        options: [
+          { value: 12301, labelText: 'Art auction', options: [] },
+          { value: 12302, labelText: 'Art dealer', options: [] },
+        ],
+      },
+      { value: 104, labelText: 'Dance', options: [] },
+      { value: 600105, labelText: 'Events', options: [] },
+      { value: 600106, labelText: 'Festival', options: [] },
+      { value: 600107, labelText: 'Funding body', options: [] },
+      { value: 107, labelText: 'Heritage', options: [] },
+      { value: 600109, labelText: 'Librarian & archivist', options: [] },
+      { value: 108, labelText: 'Museums & galleries', options: [] },
+      { value: 109, labelText: 'Music', options: [] },
+      { value: 600110, labelText: 'Press, publicity & PR', options: [] },
+      { value: 600111, labelText: 'Promoter', options: [] },
+      { value: 110, labelText: 'Theatre', options: [] },
+      { value: 600113, labelText: 'Venue', options: [] },
+      { value: 106, labelText: 'Visual arts', options: [] },
+      { value: 600114, labelText: 'Writing & literature', options: [] },
+    ],
+  },
+  {
+    value: 111,
+    labelText: 'Charities',
+    options: [
+      { value: 112, labelText: 'Advice', options: [] },
+      { value: 113, labelText: 'Advocacy', options: [] },
+      { value: 114, labelText: 'Animal', options: [] },
+      { value: 600116, labelText: 'Arts & culture', options: [] },
+      { value: 600117, labelText: 'Charity & volunteering support', options: [] },
+      { value: 115, labelText: 'Children', options: [] },
+      { value: 600118, labelText: 'Community development', options: [] },
+      { value: 600119, labelText: 'Crime', options: [] },
+      { value: 116, labelText: 'Disability', options: [] },
+      { value: 117, labelText: 'Environment', options: [] },
+      { value: 118, labelText: 'Equality', options: [] },
+      { value: 600120, labelText: 'Faith-based', options: [] },
+      { value: 119, labelText: 'Fundraising', options: [] },
+      { value: 121, labelText: 'Health', options: [] },
+      { value: 600122, labelText: 'Housing & homelessness', options: [] },
+      { value: 348, labelText: 'Human rights', options: [] },
+      { value: 122, labelText: 'International', options: [] },
+      { value: 300, labelText: 'Mental health', options: [] },
+      { value: 600123, labelText: 'Policy & research', options: [] },
+      { value: 600124, labelText: 'Poverty relief', options: [] },
+      { value: 600125, labelText: 'Social welfare', options: [] },
+      { value: 349, labelText: 'Trustee', options: [] },
+      { value: 600126, labelText: 'Volunteer management', options: [] },
+    ],
+  },
+  { value: 124, labelText: 'Construction', options: [] },
+  { value: 142, labelText: 'Design', options: [] },
+  {
+    value: 137,
+    labelText: 'Engineering',
+    options: [
+      { value: 138, labelText: 'General', options: [] },
+      { value: 139, labelText: 'Manufacturing', options: [] },
+      { value: 140, labelText: 'Utility', options: [] },
+    ],
+  },
+  {
+    value: 141,
+    labelText: 'Environment',
+    options: [
+      { value: 600131, labelText: 'Agriculture & land management', options: [] },
+      { value: 600132, labelText: 'Auditing', options: [] },
+      { value: 147, labelText: 'Built environment', options: [] },
+      { value: 600136, labelText: 'Climate change', options: [] },
+      { value: 600137, labelText: 'Corporate social responsibility', options: [] },
+      { value: 600138, labelText: 'Ecology & conservation', options: [] },
+      { value: 600139, labelText: 'Energy efficiency & renewable energy', options: [] },
+      { value: 600140, labelText: 'Energy management', options: [] },
+      { value: 143, labelText: 'Environmental education', options: [] },
+      { value: 600141, labelText: 'Environmental management', options: [] },
+      { value: 145, labelText: 'Green & clean technology', options: [] },
+      { value: 600143, labelText: 'International development', options: [] },
+      { value: 146, labelText: 'Policy, legislation & strategy', options: [] },
+      { value: 148, labelText: 'Recycling & waste management', options: [] },
+      { value: 600145, labelText: 'Supply chain', options: [] },
+      { value: 600146, labelText: 'Sustainability', options: [] },
+      { value: 600147, labelText: 'Water & wastewater', options: [] },
+    ],
+  },
+];
+
+const defaultI18n = {
+  selectedTermsLabel: 'Selected terms:',
+  noResults: 'No matching options',
+  optionsSelectedSingular: '1 option selected',
+  optionsSelectedPlural: '{count} options selected',
+  optionsFoundSingular: '1 option found',
+  optionsFoundPlural: '{count} options found',
+};
+
+const variant = (name, context, { note } = {}) => ({
+  name,
+  context: {
+    sectionTitle: `<h2>${name}</h2>${note ? `<p><em>${note}</em></p>` : ''}`,
+    i18n: defaultI18n,
+    ...context,
+  },
+});
+
+module.exports = {
+  title: 'Category Picker',
+  status: 'ready',
+  context: {
+    sectionTitle: '<h2>Default</h2>',
+    searchPlaceholder: 'Search or select…',
+    i18n: defaultI18n,
+    checkboxList: {
+      labelText: 'Job sectors',
+      id: 'category-picker',
+      selectedOptions: [142, 12302],
+      i18n: {
+        accordionTrigger: 'Please find more options under {label}',
+      },
+      options,
+    },
+  },
+  variants: [
+    variant('With error state', {
+      checkboxList: {
+        id: 'category-picker-error',
+        state: 'error',
+        validationError: 'This field is required',
+        selectedOptions: [142, 12302],
+      },
+    }),
+    variant(
+      'No preselection',
+      {
+        checkboxList: {
+          id: 'category-picker-empty',
+          selectedOptions: [],
+        },
+      },
+      { note: 'Empty state — click input to reveal dropdown.' },
+    ),
+    variant(
+      'i18n example',
+      {
+        searchPlaceholder: 'Rechercher ou sélectionner…',
+        i18n: {
+          selectedTermsLabel: 'Termes sélectionnés :',
+          noResults: 'Aucune option correspondante',
+          optionsSelectedSingular: '1 option sélectionnée',
+          optionsSelectedPlural: '{count} options sélectionnées',
+          optionsFoundSingular: '1 option trouvée',
+          optionsFoundPlural: '{count} options trouvées',
+        },
+        checkboxList: {
+          labelText: "Secteurs d'activité",
+          id: 'category-picker-i18n',
+          selectedOptions: [142, 12302],
+          i18n: {
+            accordionTrigger: "Voir plus d'options sous {label}",
+          },
+          options,
+        },
+      },
+      { note: 'Example with French translations for all i18n strings.' },
+    ),
+  ],
+};

package/src/components/inputs/category-picker/category-picker.js

@@ -0,0 +1,302 @@
+const ITEM = '.mds-form-check';
+const CHECKBOX = '.mds-form-check__input';
+const LABEL = '.mds-form-check__label';
+const NESTED = '.mds-form-check__nested-container';
+const PILL = '.mds-category-picker__pill';
+const CLEAR = '.mds-category-picker__clear-pill';
+
+const DEFAULT_I18N = {
+  optionsSelectedSingular: '1 option selected',
+  optionsSelectedPlural: '{count} options selected',
+  optionsFoundSingular: '1 option found',
+  optionsFoundPlural: '{count} options found',
+};
+
+export class MdsCategoryPicker extends HTMLElement {
+  #controller;
+  #pillbox;
+  #pillTemplate;
+  #buttonTemplate;
+  #searchInput;
+  #inputWrapper;
+  #dropdown;
+  #liveRegion;
+  #noResults;
+  #i18n;
+  #buttonToCheckbox = new WeakMap();
+  #isOpen = false;
+
+  connectedCallback() {
+    const templates = this.querySelector('.mds-category-picker__templates');
+    this.#pillbox = this.querySelector('.mds-category-picker__pillbox');
+    this.#searchInput = this.querySelector('.mds-category-picker__search');
+    this.#inputWrapper = this.querySelector('.mds-category-picker__input-wrapper');
+    this.#dropdown = this.querySelector('.mds-category-picker__dropdown');
+    this.#liveRegion = this.querySelector('.mds-category-picker__live-region');
+    this.#noResults = this.querySelector('.mds-category-picker__no-results');
+
+    if (!templates || !this.#pillbox || !this.#searchInput || !this.#dropdown) return;
+
+    try {
+      this.#i18n = { ...DEFAULT_I18N, ...JSON.parse(this.getAttribute('i18n') || '{}') };
+    } catch {
+      this.#i18n = DEFAULT_I18N;
+    }
+
+    this.#pillTemplate = templates.querySelector(PILL);
+    this.#buttonTemplate = templates.querySelector(CLEAR);
+    if (!this.#pillTemplate || !this.#buttonTemplate) return;
+    templates.remove();
+
+    this.#controller = new AbortController();
+    const o = { signal: this.#controller.signal };
+
+    this.#pillbox.addEventListener('click', this.#onRemovePill, o);
+    this.#dropdown.addEventListener('change', this.#onCheckboxChange, o);
+    this.#searchInput.addEventListener('blur', this.#onSearchBlur, o);
+    this.#searchInput.addEventListener('input', this.#onSearchInput, o);
+    this.#searchInput.addEventListener('keydown', this.#onSearchKeydown, o);
+    this.#inputWrapper.addEventListener('click', () => this.#searchInput.focus(), o);
+    this.#searchInput.addEventListener('focus', () => this.#open(), o);
+    this.#dropdown.addEventListener(
+      'mousedown',
+      (e) => {
+        if (e.target !== this.#searchInput) e.preventDefault();
+      },
+      o,
+    );
+    this.#dropdown.addEventListener(
+      'focusout',
+      (e) => {
+        if (!e.relatedTarget || !this.contains(e.relatedTarget)) this.#close();
+      },
+      o,
+    );
+    this.#dropdown.addEventListener(
+      'keydown',
+      (e) => {
+        if (e.key === 'Escape') {
+          this.#close();
+          this.#searchInput.focus();
+        }
+      },
+      o,
+    );
+    document.addEventListener(
+      'click',
+      (e) => {
+        if (!e.composedPath().includes(this)) this.#close();
+      },
+      o,
+    );
+
+    this.#syncSelection();
+  }
+
+  disconnectedCallback() {
+    this.#controller?.abort();
+  }
+
+  // --- Open / Close ---
+
+  #open() {
+    if (this.#isOpen) return;
+    this.#isOpen = true;
+    this.classList.add('mds-category-picker--open');
+    this.#searchInput.setAttribute('aria-expanded', 'true');
+  }
+
+  #close() {
+    if (!this.#isOpen) return;
+    this.#isOpen = false;
+    this.classList.remove('mds-category-picker--open');
+    this.#searchInput.setAttribute('aria-expanded', 'false');
+    this.#searchInput.value = '';
+    this.#resetFilter();
+  }
+
+  #onSearchBlur = (e) => {
+    const related = e.relatedTarget;
+    if (related && (this.#dropdown.contains(related) || this.#inputWrapper.contains(related))) return;
+    this.#close();
+  };
+
+  // --- Selection ---
+
+  #syncSelection = () => {
+    this.#pillbox.replaceChildren();
+    this.#buttonToCheckbox = new WeakMap();
+    const cls = 'mds-form-check--has-selection';
+
+    for (const item of this.#dropdown.querySelectorAll(ITEM)) item.classList.remove(cls);
+
+    for (const cb of this.#dropdown.querySelectorAll(`${CHECKBOX}:checked`)) {
+      this.#addPill(cb);
+
+      let el = cb.closest(ITEM)?.parentElement;
+      while (el && el !== this.#dropdown) {
+        if (el.matches(ITEM)) el.classList.add(cls);
+        el = el.parentElement;
+      }
+    }
+  };
+
+  #addPill(checkbox) {
+    const path = checkbox.dataset.path;
+    if (!path) return;
+
+    const pill = this.#pillTemplate.cloneNode(true);
+    const button = this.#buttonTemplate.cloneNode(true);
+    button.setAttribute('aria-label', `${button.getAttribute('aria-label')} ${path}`);
+    const textSpan = document.createElement('span');
+    textSpan.className = 'mds-category-picker__pill-text';
+    textSpan.textContent = path;
+    pill.appendChild(textSpan);
+    pill.appendChild(button);
+    this.#pillbox.appendChild(pill);
+    this.#buttonToCheckbox.set(button, checkbox);
+  }
+
+  #onRemovePill = ({ target }) => {
+    const cb = this.#buttonToCheckbox.get(target.closest(CLEAR));
+    if (cb) {
+      cb.checked = false;
+      cb.dispatchEvent(new Event('change', { bubbles: true }));
+    }
+  };
+
+  #onCheckboxChange = () => {
+    this.#syncSelection();
+    this.#searchInput.value = '';
+    this.#resetFilter();
+    const count = this.#dropdown.querySelectorAll(`${CHECKBOX}:checked`).length;
+    this.#announce(this.#getAnnouncementMessage('optionsSelectedSingular', 'optionsSelectedPlural', count));
+  };
+
+  // --- Search / Filter ---
+
+  #onSearchInput = () => {
+    const query = this.#searchInput.value.trim();
+
+    if (query.length >= 2) {
+      this.#filterOptions(query);
+    } else {
+      this.#resetFilter();
+    }
+  };
+
+  #filterOptions(query) {
+    const q = query.toLowerCase();
+    const items = this.#dropdown.querySelectorAll(ITEM);
+    const visibleParents = new Set();
+    const directMatchParents = new Set();
+
+    for (const item of items) {
+      const text = item.querySelector(LABEL)?.textContent.trim().toLowerCase() || '';
+      if (!text) continue;
+
+      if (item.querySelector(NESTED)) {
+        if (text.includes(q)) {
+          visibleParents.add(item);
+          directMatchParents.add(item);
+        }
+        continue;
+      }
+
+      item.hidden = !text.includes(q);
+      if (!item.hidden) {
+        let el = item.parentElement;
+        while (el && el !== this.#dropdown) {
+          if (el.matches(ITEM)) visibleParents.add(el);
+          el = el.parentElement;
+        }
+      }
+    }
+
+    for (const item of items) {
+      const nested = item.querySelector(NESTED);
+      if (!nested) continue;
+
+      if (visibleParents.has(item)) {
+        item.hidden = false;
+        item.querySelector('.mds-checkbox-accordion__button')?.setAttribute('aria-expanded', 'true');
+        if (directMatchParents.has(item)) {
+          for (const child of nested.querySelectorAll(ITEM)) child.hidden = false;
+        }
+      } else {
+        item.hidden = true;
+      }
+    }
+
+    let count = 0;
+    for (const item of items) if (!item.hidden) count++;
+
+    this.#showNoResults(count === 0);
+    this.#announce(this.#getAnnouncementMessage('optionsFoundSingular', 'optionsFoundPlural', count));
+  }
+
+  #resetFilter() {
+    for (const item of this.#dropdown.querySelectorAll(ITEM)) item.hidden = false;
+    this.#showNoResults(false);
+  }
+
+  #showNoResults(show) {
+    this.#noResults?.classList.toggle('mds-category-picker__no-results--visible', show);
+  }
+
+  // --- Keyboard ---
+
+  #onSearchKeydown = (e) => {
+    switch (e.key) {
+      case 'Escape':
+        this.#close();
+        this.#searchInput.blur();
+        break;
+      case 'ArrowDown': {
+        e.preventDefault();
+        if (!this.#isOpen) this.#open();
+        for (const item of this.#dropdown.querySelectorAll(ITEM)) {
+          if (item.hidden) continue;
+          const cb = item.querySelector(CHECKBOX);
+          if (cb) {
+            cb.focus();
+            break;
+          }
+        }
+        break;
+      }
+      case 'Backspace':
+        if (this.#searchInput.value === '') {
+          const pills = this.#pillbox.querySelectorAll(PILL);
+          const lastPill = pills[pills.length - 1];
+          if (!lastPill) break;
+          const cb = this.#buttonToCheckbox.get(lastPill.querySelector(CLEAR));
+          if (cb) {
+            cb.checked = false;
+            cb.dispatchEvent(new Event('change', { bubbles: true }));
+          }
+        }
+        break;
+      case 'Tab':
+        this.#close();
+        break;
+      default:
+        break;
+    }
+  };
+
+  // --- Announcements ---
+
+  #getAnnouncementMessage(singularKey, pluralKey, count) {
+    if (count === 1) return this.#i18n[singularKey];
+    return this.#i18n[pluralKey].replace('{count}', String(count));
+  }
+
+  #announce(message) {
+    if (!this.#liveRegion) return;
+    this.#liveRegion.textContent = '';
+    requestAnimationFrame(() => {
+      this.#liveRegion.textContent = message;
+    });
+  }
+}