@madgex/design-system 14.2.0 → 14.3.1

package/src/components/conditional-section/conditional-section.spec.js

@@ -0,0 +1,402 @@
+// eslint-disable-next-line n/no-unpublished-import
+import { describe, it, expect, afterEach } from 'vitest';
+import { MdsConditionalSection, shouldShow } from './conditional-section.js';
+
+if (!customElements.get('mds-conditional-section')) {
+  customElements.define('mds-conditional-section', MdsConditionalSection);
+}
+
+function emitInput(target) {
+  target.dispatchEvent(new Event('input', { bubbles: true }));
+}
+
+function mountScenario({ inputsHtml, fieldName, showWhen, includeShowWhen = true }) {
+  const container = document.createElement('div');
+  const showWhenAttr = includeShowWhen ? `show-when="${String(showWhen).replace(/"/g, '"')}"` : '';
+  container.innerHTML = `
+    <form id="test-conditional-form">
+      ${inputsHtml}
+      <mds-conditional-section field-name="${fieldName}" ${showWhenAttr}>
+        <p data-testid="conditional-content">Conditional content</p>
+      </mds-conditional-section>
+    </form>
+  `;
+  document.body.appendChild(container);
+  const form = container.querySelector('form');
+  const section = container.querySelector('mds-conditional-section');
+  return { container, form, section };
+}
+
+describe('shouldShow', () => {
+  it('is true when any checked value matches a comma-separated trigger (OR)', () => {
+    const form = document.createElement('form');
+    form.innerHTML = `
+      <input type="checkbox" name="i" value="sports" checked />
+      <input type="checkbox" name="i" value="music" />
+    `;
+    expect(shouldShow(form.elements.i, 'sports,music')).toBe(true);
+
+    form.querySelector('[value="sports"]').checked = false;
+    form.querySelector('[value="music"]').checked = true;
+    expect(shouldShow(form.elements.i, 'sports,music')).toBe(true);
+  });
+
+  it('is false when no checked value matches triggers', () => {
+    const form = document.createElement('form');
+    form.innerHTML = `
+      <input type="checkbox" name="i" value="sports" />
+      <input type="checkbox" name="i" value="music" />
+      <input type="checkbox" name="i" value="travel" checked />
+    `;
+    expect(shouldShow(form.elements.i, 'sports,music')).toBe(false);
+  });
+
+  it('is false when a checkbox group has nothing checked', () => {
+    const form = document.createElement('form');
+    form.innerHTML = `
+      <input type="checkbox" name="i" value="sports" />
+      <input type="checkbox" name="i" value="music" />
+    `;
+    expect(shouldShow(form.elements.i, 'sports')).toBe(false);
+  });
+
+  it('trims trigger segments and ignores empty parts', () => {
+    const form = document.createElement('form');
+    form.innerHTML = `
+      <input type="checkbox" name="i" value="a" checked />
+      <input type="checkbox" name="i" value="b" />
+    `;
+    expect(shouldShow(form.elements.i, ' a , b ')).toBe(true);
+  });
+
+  it('is false when show-when is null or empty', () => {
+    const form = document.createElement('form');
+    form.innerHTML = `<input type="checkbox" name="i" value="x" checked />`;
+    expect(shouldShow(form.elements.i, null)).toBe(false);
+    expect(shouldShow(form.elements.i, '')).toBe(false);
+  });
+
+  it('for a lone checkbox uses true/false against triggers', () => {
+    const form = document.createElement('form');
+    form.innerHTML = '<input type="checkbox" name="c" />';
+    const field = form.elements.c;
+    expect(shouldShow(field, 'false')).toBe(true);
+    expect(shouldShow(field, 'true')).toBe(false);
+    field.checked = true;
+    expect(shouldShow(field, 'true')).toBe(true);
+    expect(shouldShow(field, 'false')).toBe(false);
+  });
+
+  it('for a lone checkbox with a custom value matches show-when against that value when checked', () => {
+    const form = document.createElement('form');
+    form.innerHTML = '<input type="checkbox" name="c" value="yes" />';
+    const field = form.elements.c;
+    expect(shouldShow(field, 'yes')).toBe(false);
+    field.checked = true;
+    expect(shouldShow(field, 'yes')).toBe(true);
+    expect(shouldShow(field, 'no')).toBe(false);
+  });
+
+  it('for a lone checkbox with a custom value still supports show-when true/false', () => {
+    const form = document.createElement('form');
+    form.innerHTML = '<input type="checkbox" name="c" value="yes" />';
+    const field = form.elements.c;
+    field.checked = true;
+    expect(shouldShow(field, 'true')).toBe(true);
+    expect(shouldShow(field, 'false')).toBe(false);
+    field.checked = false;
+    expect(shouldShow(field, 'false')).toBe(true);
+  });
+
+  it('for a checkbox group matches checked values', () => {
+    const form = document.createElement('form');
+    form.innerHTML = `
+      <input type="checkbox" name="i" value="sports" />
+      <input type="checkbox" name="i" value="music" checked />
+      <input type="checkbox" name="i" value="travel" />
+    `;
+    expect(shouldShow(form.elements.i, 'music')).toBe(true);
+  });
+
+  it('uses "on" when a checked checkbox has no value attribute', () => {
+    const form = document.createElement('form');
+    form.innerHTML = `
+      <input type="checkbox" name="i" checked />
+      <input type="checkbox" name="i" />
+    `;
+    expect(shouldShow(form.elements.i, 'on')).toBe(true);
+  });
+
+  it('for a radio group matches the selected value', () => {
+    const form = document.createElement('form');
+    form.innerHTML = `
+      <input type="radio" name="r" value="a" />
+      <input type="radio" name="r" value="b" checked />
+    `;
+    expect(shouldShow(form.elements.r, 'b')).toBe(true);
+    expect(shouldShow(form.elements.r, 'a')).toBe(false);
+  });
+
+  it('reads multiple same-name controls from a RadioNodeList', () => {
+    const form = document.createElement('form');
+    form.innerHTML = `
+      <input type="checkbox" name="i" value="a" />
+      <input type="checkbox" name="i" value="b" />
+    `;
+    const list = form.elements.i;
+    expect(list).toBeInstanceOf(RadioNodeList);
+    expect(list.length).toBe(2);
+    list[1].checked = true;
+    expect(shouldShow(list, 'b')).toBe(true);
+  });
+
+  it('for a multiple select matches any selected option against comma-separated triggers', () => {
+    const form = document.createElement('form');
+    form.innerHTML = `
+      <select name="skills" id="skills" multiple>
+        <option value="js">JavaScript</option>
+        <option value="css">CSS</option>
+        <option value="html">HTML</option>
+      </select>
+    `;
+    const select = form.elements.skills;
+    expect(shouldShow(select, 'js,css')).toBe(false);
+
+    select.options[1].selected = true;
+    expect(shouldShow(select, 'js,css')).toBe(true);
+
+    select.options[1].selected = false;
+    select.options[2].selected = true;
+    expect(shouldShow(select, 'js,css')).toBe(false);
+  });
+
+  it('for a multiple select matches when a non-first selected option matches show-when alone', () => {
+    const form = document.createElement('form');
+    form.innerHTML = `
+      <select name="skills" id="skills" multiple>
+        <option value="js">JavaScript</option>
+        <option value="css">CSS</option>
+      </select>
+    `;
+    const select = form.elements.skills;
+    select.options[0].selected = true;
+    select.options[1].selected = true;
+    expect(shouldShow(select, 'css')).toBe(true);
+  });
+
+  it('for a multiple select stays visible while any matching option remains selected', () => {
+    const form = document.createElement('form');
+    form.innerHTML = `
+      <select name="skills" id="skills" multiple>
+        <option value="js">JavaScript</option>
+        <option value="css">CSS</option>
+      </select>
+    `;
+    const select = form.elements.skills;
+    select.options[0].selected = true;
+    select.options[1].selected = true;
+    expect(shouldShow(select, 'js,css')).toBe(true);
+
+    select.options[0].selected = false;
+    expect(shouldShow(select, 'js,css')).toBe(true);
+
+    select.options[1].selected = false;
+    expect(shouldShow(select, 'js,css')).toBe(false);
+  });
+});
+
+describe('MdsConditionalSection', () => {
+  let container;
+
+  afterEach(() => {
+    container?.remove();
+    container = undefined;
+  });
+
+  describe('checkbox group', () => {
+    it('shows when a non-first checkbox matching show-when is checked', () => {
+      ({ container } = mountScenario({
+        fieldName: 'interests',
+        showWhen: 'music',
+        inputsHtml: `
+          <input type="checkbox" name="interests" value="sports" id="cb-sports" />
+          <input type="checkbox" name="interests" value="music" id="cb-music" />
+          <input type="checkbox" name="interests" value="travel" id="cb-travel" />
+        `,
+      }));
+      const section = container.querySelector('mds-conditional-section');
+      expect(section.hidden).toBe(true);
+
+      const music = container.querySelector('#cb-music');
+      music.checked = true;
+      emitInput(music);
+
+      expect(section.hidden).toBe(false);
+    });
+
+    it('matches any comma-separated trigger (OR)', () => {
+      ({ container } = mountScenario({
+        fieldName: 'interests',
+        showWhen: 'sports,music',
+        inputsHtml: `
+          <input type="checkbox" name="interests" value="sports" id="cb-sports" />
+          <input type="checkbox" name="interests" value="music" id="cb-music" />
+          <input type="checkbox" name="interests" value="travel" id="cb-travel" />
+        `,
+      }));
+      const section = container.querySelector('mds-conditional-section');
+      const travel = container.querySelector('#cb-travel');
+      travel.checked = true;
+      emitInput(travel);
+      expect(section.hidden).toBe(true);
+
+      const music = container.querySelector('#cb-music');
+      music.checked = true;
+      emitInput(music);
+      expect(section.hidden).toBe(false);
+    });
+
+    it('stays visible if one matching trigger is unchecked but another remains checked', () => {
+      ({ container } = mountScenario({
+        fieldName: 'interests',
+        showWhen: 'sports,music',
+        inputsHtml: `
+          <input type="checkbox" name="interests" value="sports" id="cb-sports" />
+          <input type="checkbox" name="interests" value="music" id="cb-music" />
+        `,
+      }));
+      const section = container.querySelector('mds-conditional-section');
+      const sports = container.querySelector('#cb-sports');
+      const music = container.querySelector('#cb-music');
+      sports.checked = true;
+      music.checked = true;
+      emitInput(sports);
+
+      expect(section.hidden).toBe(false);
+
+      sports.checked = false;
+      emitInput(sports);
+      expect(section.hidden).toBe(false);
+
+      music.checked = false;
+      emitInput(music);
+      expect(section.hidden).toBe(true);
+    });
+  });
+
+  describe('regressions', () => {
+    it('single checkbox with show-when true toggles visibility', () => {
+      ({ container } = mountScenario({
+        fieldName: 'agree',
+        showWhen: 'true',
+        inputsHtml: '<input type="checkbox" name="agree" id="agree" />',
+      }));
+      const section = container.querySelector('mds-conditional-section');
+      const cb = container.querySelector('#agree');
+      expect(section.hidden).toBe(true);
+      cb.checked = true;
+      emitInput(cb);
+      expect(section.hidden).toBe(false);
+    });
+
+    it('hide-salary pattern: show-when false when checkbox unchecked', () => {
+      ({ container } = mountScenario({
+        fieldName: 'HideSalary',
+        showWhen: 'false',
+        inputsHtml: '<input type="checkbox" name="HideSalary" id="HideSalary" />',
+      }));
+      const section = container.querySelector('mds-conditional-section');
+      expect(section.hidden).toBe(false);
+      const cb = container.querySelector('#HideSalary');
+      cb.checked = true;
+      emitInput(cb);
+      expect(section.hidden).toBe(true);
+    });
+
+    it('single checkbox with custom value and show-when toggles visibility', () => {
+      ({ container } = mountScenario({
+        fieldName: 'newsletter',
+        showWhen: 'weekly',
+        inputsHtml: '<input type="checkbox" name="newsletter" id="newsletter" value="weekly" />',
+      }));
+      const section = container.querySelector('mds-conditional-section');
+      const cb = container.querySelector('#newsletter');
+      expect(section.hidden).toBe(true);
+      cb.checked = true;
+      emitInput(cb);
+      expect(section.hidden).toBe(false);
+    });
+
+    it('radio group show-when matches selected value', () => {
+      ({ container } = mountScenario({
+        fieldName: 'option',
+        showWhen: 'Broccoli',
+        inputsHtml: `
+          <input type="radio" name="option" value="Donkey" id="r1" />
+          <input type="radio" name="option" value="Broccoli" id="r2" />
+        `,
+      }));
+      const section = container.querySelector('mds-conditional-section');
+      expect(section.hidden).toBe(true);
+      container.querySelector('#r2').checked = true;
+      emitInput(container.querySelector('#r2'));
+      expect(section.hidden).toBe(false);
+    });
+
+    it('select show-when matches option value', () => {
+      ({ container } = mountScenario({
+        fieldName: 'pets',
+        showWhen: 'cat',
+        inputsHtml: `
+          <select name="pets" id="pets">
+            <option value="">Choose</option>
+            <option value="dog">Dog</option>
+            <option value="cat">Cat</option>
+          </select>
+        `,
+      }));
+      const section = container.querySelector('mds-conditional-section');
+      const sel = container.querySelector('#pets');
+      sel.value = 'cat';
+      emitInput(sel);
+      expect(section.hidden).toBe(false);
+    });
+
+    it('multiple select show-when matches any selected option (OR)', () => {
+      ({ container } = mountScenario({
+        fieldName: 'skills',
+        showWhen: 'js,css',
+        inputsHtml: `
+          <label for="skills">Pick your skills (hold Ctrl/Cmd to select several):</label>
+          <select name="skills" id="skills" multiple size="3">
+            <option value="js">JavaScript</option>
+            <option value="css">CSS</option>
+            <option value="html">HTML</option>
+          </select>
+        `,
+      }));
+      const section = container.querySelector('mds-conditional-section');
+      const sel = container.querySelector('#skills');
+      expect(section.hidden).toBe(true);
+
+      sel.options[1].selected = true;
+      emitInput(sel);
+      expect(section.hidden).toBe(false);
+    });
+  });
+
+  describe('missing show-when', () => {
+    it('keeps section hidden when show-when attribute is omitted', () => {
+      ({ container } = mountScenario({
+        fieldName: 'interests',
+        showWhen: '',
+        includeShowWhen: false,
+        inputsHtml: `
+          <input type="checkbox" name="interests" value="sports" checked />
+        `,
+      }));
+      const section = container.querySelector('mds-conditional-section');
+      expect(section.hidden).toBe(true);
+    });
+  });
+});

package/src/components/inputs/combobox/README.md

@@ -2,34 +2,34 @@
 
 This component provides autocomplete search functionality to select an option from a list of options.
 
-Options can be provided via the `options` parameter, or obtained from an API using the `apiUrl` parameter.
-
-`value` is an Object or Array of Objects representing the selected option or options.
+Options can be provided via `<option value="value">label</option>` children, or obtained from an API using the `apiUrl` parameter.
 
 ## Parameters - Nunjucks
 
 - `id`: the id of your combobox **required**
 - `name`: the name of the input for form submission. Uses ID unless specified - **recommended**
 - `labelText`: the text used in the label **required**
-- `value`: the populated option `object` ( `{ label: 'Orange', value: 45 }`) or `array` of option `objects` ( `[{ label: 'Orange', value: 45 }, { label: 'Green', value: 33 }]`)
 - `searchText`: _Not_ the value, but the current text inside the search input.
-- `options`: an `array`, e.g `[{ label: 'Orange', value: 45 }]`. Populates both mds-combobox, and fallback select options
-- `apiUrl`: when populated, `options` is ignored and data is fetched from an API URL instead
+- `apiUrl`: when populated, options data is fetched from an API URL
 - `apiQueryKey`: the query parameter name added to `apiUrl` - (defaults to 'searchText')
 - `apiOptionsPath`: where to grab an array of options on api response, e.g. `data.options` would be an array of options. leave undefined to use root api response as array
-- `optionLabelPath`: where to grab the visual label from the option object e.g. 'label' or 'title' or 'nested.object.label' (defaults to `label`)
-- `optionValuePath`: where to grab the value from the option object e.g. `value` or `nested.object.value` (defaults to `value`)
+- `apiOptionLabelPath`: relative to options object returned from API response, e.g. `label` or `title` or `nested.object.label` (defaults to `label`)
+- `apiOptionValuePath`: relative to options object returned from API response, e.g. `value` or `score` or `nested.object.value` (defaults to `value`)
 - `multiple`: Boolean, whether to treat `value` input and output as an Array, or a singular. Also to display pills. default `false`
 - `fallbackTo`: the form element to use as a fallback. Should be either 'select' or 'input' **recommended** (see notes underneath)
-- `placeholder`: the placeholder for your input (defaults to 'Please select') **recommended**
+- `fallbackValue`: only when `fallbackTo` is `input`, the `value` attribute of the fallback `input` element
+- `placeholder`: the placeholder for your input **recommended**
 - `classes`: add extra classes to the trigger
 - `helpText`: Helper text to display under the label
 - `tooltipMessage`: Toggles a tooltip with this message to appear on the input
 - `validationError`: The error message provided by validation
 - `state`: The current state of the input, currently the only allowed value is `error`
-- `type`: applied as data-type` attribute, the name of the options api e.g "location-lookup"
+- `type`: applied as `data-type` attribute, the name of the options api e.g "location-lookup"
 - `i18n`: an `object`, Text to translate/customise
 - `minSearchCharacters`: The minimum number of characters inside the input before a search is performed to avoid low specificity searches. This should be matched by your implementation's search handler.
+- `attributes`: an `object`, attribute key/values applied directly to `mds-combobox` element
+- `hideLabel` — Boolean, visually hides the label.
+- `optional` - Boolean, marks field as optional in the label only
 
 ```
 i18n: {
@@ -48,13 +48,7 @@ i18n: {
 
 ## Usage
 
-MdsCombobox usage revolves around either options provided by `params.options` or an API (`apiUrl` in use), and being in `multiple` mode via `params.multiple`.
-If `multiple` mode is true,`params.value` must be undefined or an `array`, otherwise undefined or an `object`.
-
-The params `value`, `options`, `optionLabelPath` and `optionValuePath` are tightly coupled and must be compatible with each other:
-
-- `options`: an array of objects, each object has the property stated by `optionLabelPath` and `optionValuePath`
-- `value`: an object ( or array of objects if `multiple:true`), object is the same shape as the ones in `options`, each object has the property stated by `optionLabelPath` and `optionValuePath`
+MdsCombobox usage revolves around options provided by `<option value="">label</option>` child elements as available options and the initial value comes from `<option selected>` children, and optionally an API (`apiUrl` in use), and being in `multiple` mode via `params.multiple`.
 
 ## Fallback
 
@@ -63,65 +57,52 @@ When JavaScript is unavailable, the combobox will gracefully degrade to a native
 Both fallback elements share the same `id` as the combobox to ensure the label remains properly associated. However, the fallback's `name` attribute will be `[name]_fallback` to distinguish it from the JavaScript-enabled version. This allows your server-side code to detect when the fallback was used and handle the form submission appropriately.
 
 **Choosing a fallback type:**
+
 - Use `fallbackTo: 'select'` when you have a static, predefined list of options that work well in a standard dropdown.
 - Use `fallbackTo: 'input'` when options are dynamic (from an API) or when you prefer a text input. With a text input fallback, users can type and submit values that your server can then process (e.g., look up a location ID from a location name).
+- Use `fallbackValue` when using `fallbackTo: 'input'` to populate the fallback's value
 
-### Example - Single mode - no API - default option object shape
-
-As our options object uses the default property names, we don't need to specify them.
-
-```njk
-{\% call MdsCombobox({
-  id:'my-id',
-  name: 'my-combo',
-  labelText:'My Combo',
-  options: [{label: 'my-label-1', value: 'value-1'},{label: 'my-label-2', value: 'value-2'} ]
-}) \%}
-{\% endcall \%}
-
-```
-
-#### with prefilled value
+### Example - Single mode - no API - no option selected
 
 ```njk
 {\% call MdsCombobox({
   id:'my-id',
   name: 'my-combo',
   labelText:'My Combo',
-  value: {value: 'value-2', label: 'my-label-2'},
-  options: [{label: 'my-label-1', value: 'value-1'},{label: 'my-label-2', value: 'value-2'} ]
 }) \%}
+  <option value="value-1">My label 1</option>
+  <option value="value-2">My label 2</option>
 {\% endcall \%}
 
 ```
 
-### Example - Multiple mode - no API - default option object shape
+#### with pre-selected value
 
 ```njk
 {\% call MdsCombobox({
   id:'my-id',
   name: 'my-combo',
   labelText:'My Combo',
-  options: [{label: 'my-label-1', value: 'value-1'},{label: 'my-label-2', value: 'value-2'} ],
-  multiple: true
+  fallbackTo:'input',
+  fallbackValue:'value-2'
 }) \%}
+  <option value="value-1">My label 1</option>
+  <option value="value-2" selected>My label 2</option>
 {\% endcall \%}
 
 ```
 
-#### with prefilled value
-
-Note the value should be an array when using multiple mode.
+### Example - Multiple mode - no API
 
 ```njk
 {\% call MdsCombobox({
   id:'my-id',
   name: 'my-combo',
   labelText:'My Combo',
-  value: [{value: 'value-2', label: 'my-label-2'}],
-  options: [{label: 'my-label-1', value: 'value-1'},{label: 'my-label-2', value: 'value-2'} ],
   multiple: true
 }) \%}
+  <option value="value-1">My label 1</option>
+  <option value="value-2">My label 2</option>
 {\% endcall \%}
 
 ```
@@ -138,8 +119,8 @@ like so `[{word: 'something', score: 12},...]`. It also used `?keyword` for the
   labelText:'My Combo',
   apiUrl: '/api/location-lookup',
   apiQueryKey: 'keyword',
-  optionLabelPath: 'word',
-  optionValuePath: 'score'
+  apiOptionLabelPath: 'word',
+  apiOptionValuePath: 'score'
 }) \%}
 {\% endcall \%}
 
@@ -152,12 +133,13 @@ like so `[{word: 'something', score: 12},...]`. It also used `?keyword` for the
   id:'my-id',
   name: 'my-combo',
   labelText:'My Combo',
-  value: {word: 'my-label-2', score: 'value-2'},
   apiUrl: '/api/location-lookup',
   apiQueryKey: 'keyword',
-  optionLabelPath: 'word',
-  optionValuePath: 'score'
+  apiOptionLabelPath: 'word',
+  apiOptionValuePath: 'score'
 }) \%}
+{# we can render selected options on the server even when using API #}
+  <option value="value-2" selected>My label 2</option>
 {\% endcall \%}
 
 ```
@@ -183,18 +165,18 @@ options:
 
 #### with prefilled value
 
-Note the value is an array for multiple mode.
-
 ```njk
 {\% call MdsCombobox({
   id:'my-id',
   name: 'my-combo',
   labelText:'My Combo',
-  value: [{label: 'my-label-1', value: 'value-1'},{label: 'my-label-2', value: 'value-2'} ],
   apiUrl: '/api/location-lookup',
   apiOptionsPath: 'data',
   multiple: true
 }) \%}
+{# we can render selected options on the server even when using API #}
+  <option value="value-1" selected>My label 1</option>
+  <option value="value-2" selected>My label 2</option>
 {\% endcall \%}
 
 ```
@@ -208,3 +190,14 @@ When Javascript is not available, either a native combobox or native input will
 aria-describedBy has been added to notify screen reader users how to interact with the autocomplete suggestions.
 
 Note: There is a known issue with the `aria-activedescendant` attribute when using VoiceOver + Safari (it works on other browsers). VO doesn't read the current option. See https://bugs.webkit.org/show_bug.cgi?id=231724
+
+## Vue only usage - `<mds-combobox/>`
+
+### Props
+
+- `value` : `{Array|Object}`, the selected option(s)
+- `options`: Alterative to child Web Component's `<option/>` elements
+
+### Events
+
+- `update:value` & `change` : on value change