@madgex/design-system 14.1.0 → 14.3.0

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/consent-gate/README.md

@@ -0,0 +1,168 @@
+# mds-consent-gate
+
+Generic consent gate for third-party embeds and widgets.
+
+The component keeps third-party markup inside a child `<template>` so it does not load or run until the user grants consent for a category. On grant it clones the template into the gate's content area; on revoke it removes the clone.
+
+## Why
+
+Many third-party embeds make outbound network requests on page load, before user intent and consent are established. This component defers those requests until explicit opt-in and provides a built-in revoke flow.
+
+## Usage
+
+Always wrap third-party content in a direct child `<template>`. Provide a fallback link in `slot="fallback"` for the no-JS / unloaded state.
+
+### Bundled (light DOM) example
+
+```html
+<mds-consent-gate category="youtube" aspect-ratio="16 / 9">
+  <span slot="heading">Video</span>
+  <template>
+    <iframe
+      src="https://www.youtube-nocookie.com/embed/aqz-KE-bpKQ"
+      title="Big Buck Bunny"
+      loading="lazy"
+      referrerpolicy="strict-origin-when-cross-origin"
+      allow="autoplay; encrypted-media; picture-in-picture; fullscreen"
+      allowfullscreen
+    ></iframe>
+  </template>
+  <a slot="fallback" href="https://www.youtube.com/watch?v=aqz-KE-bpKQ">Watch on YouTube</a>
+</mds-consent-gate>
+```
+
+### Standalone (shadow DOM, bundled CSS) example
+
+```html
+<mds-consent-gate-standalone category="youtube" aspect-ratio="16 / 9">
+  <span slot="heading">Video</span>
+  <template>
+    <iframe src="https://www.youtube-nocookie.com/embed/aqz-KE-bpKQ" title="Big Buck Bunny" loading="lazy"></iframe>
+  </template>
+  <a slot="fallback" href="https://www.youtube.com/watch?v=aqz-KE-bpKQ">Watch on YouTube</a>
+</mds-consent-gate-standalone>
+
+<script type="module" src="/path/to/mds-consent-gate-standalone.js"></script>
+```
+
+### Script placement
+
+Load the module from `<head>`. Module scripts defer by default so this does not block parsing.
+
+```html
+<head>
+  <script type="module" src="/path/to/mds-consent-gate-standalone.js"></script>
+</head>
+```
+
+Pre-mount and no-JS handling is driven by component CSS keyed off the absence of `data-state`. The fallback link remains visible until the element upgrades.
+
+## Consent behaviour
+
+Default consent is stored in `localStorage` under the key `mds-consent`.
+
+Consent is per-category. Granting one category reveals every consent-gate instance with the same `category` value, including both `<mds-consent-gate>` and `<mds-consent-gate-standalone>`. Revoking hides them all.
+
+## CMP integration
+
+Use `setConsentAdapter` to delegate to OneTrust or another CMP.
+
+> **Note:** The adapter and all consent-gate elements must share the same package instance. A standalone script loaded from a separate bundle will have its own isolated store and will not reflect consent changes made via this adapter.
+
+```js
+import { setConsentAdapter } from '@madgex/design-system';
+
+setConsentAdapter({
+  has: (category) => false,
+  grant: (category) => {},
+  revoke: (category) => {},
+  subscribe: (fn) => {
+    // call fn(category, granted) whenever consent changes
+    return () => {};
+  },
+});
+```
+
+Adapter contract:
+
+- `has(category): boolean` — must be synchronous
+- `grant(category): void`
+- `revoke(category): void`
+- `subscribe(fn): () => void`
+
+Pass `null` to restore the default localStorage adapter.
+
+## Attributes
+
+| Attribute       | Purpose                                                                                   |
+| --------------- | ----------------------------------------------------------------------------------------- |
+| `category`      | Consent category key. Required for gating behaviour.                                      |
+| `i18n`          | JSON object with optional string keys `acceptLabel` and `consentMessage`. Invalid values, empty strings, or missing keys fall back to English defaults. Omit the attribute to use defaults only. |
+| `aspect-ratio`  | Sets `--mds-consent-gate-aspect-ratio` on host. No default ratio is applied by component. |
+| `preview-image` | Sets `--mds-consent-gate-preview-image` on host (`url(...)`).                             |
+
+## Slots
+
+| Slot                       | Purpose                                                                  |
+| -------------------------- | ------------------------------------------------------------------------ |
+| default `<template>` child | Required source markup, kept inert until consent.                        |
+| `heading`                  | Optional heading content shown over the placeholder.                     |
+| `fallback`                 | Optional fallback link/content shown before consent and in error states. |
+
+## Parts
+
+Style internals via `::part(...)`:
+
+| Part              | Element                                                 |
+| ----------------- | ------------------------------------------------------- |
+| `placeholder`     | The placeholder UI container shown awaiting consent.    |
+| `consent-message` | The disclosure paragraph.                               |
+| `accept`          | The Accept button.                                      |
+| `content`         | The container the cloned template content is placed in. |
+
+## State
+
+Visibility is driven by a single `data-state` host attribute which CSS keys off:
+
+| `data-state`  | Meaning                                                   |
+| ------------- | --------------------------------------------------------- |
+| _absent_      | Pre-mount / not-yet-upgraded. Only fallback visible.      |
+| `error`       | Config error (no category or no template). Fallback only. |
+| `placeholder` | Awaiting consent. Heading + placeholder + fallback.       |
+| `consented`   | Content cloned into `[part="content"]`.                   |
+
+## Events
+
+| Event                     | Bubbles | Composed | Detail                                    |
+| ------------------------- | ------- | -------- | ----------------------------------------- |
+| `mds-consent-gate:grant`  | yes     | yes      | `{ category, container }`                 |
+| `mds-consent-gate:revoke` | yes     | yes      | `{ category }`                            |
+| `mds-consent-gate:error`  | yes     | yes      | `{ reason }`                              |
+| `mds-consent:change`      | window  | n/a      | `{ category, granted }` (default backend) |
+
+`error` reasons:
+
+- `no-category`
+- `no-template`
+- `unwrapped-content`
+
+## VPPA/GDPR safety guard
+
+Direct child network-loading elements outside `<template>` are treated as authoring errors:
+
+- `<iframe>`
+- `<embed>`
+- `<object>`
+- `<script src>`
+
+In that case the component warns in the console and emits `mds-consent-gate:error` with `reason: 'unwrapped-content'`.
+
+## Styling
+
+Use `::part(...)` for both the bundled and standalone builds. The component exposes the following CSS custom properties for theming:
+
+- `--mds-consent-gate-aspect-ratio`
+- `--mds-consent-gate-preview-image`
+- `--mds-consent-gate-bg`
+
+Internal layout uses standard DS variables (`--mds-color-button-*`, `--mds-color-neutral-darkest`, `--mds-color-text-invert`, `--mds-size-border-radius-base`).

package/src/components/consent-gate/_macro.njk

@@ -0,0 +1,30 @@
+{% from "../../sub-components/attributes/macro.njk" import MdsAttributes %}
+{#
+  MdsConsentGate macro
+
+  params:
+    category        — required, consent category key
+    i18n            — optional object `{ acceptLabel?, consentMessage? }` (passed as `i18n` host attribute via `| dump`)
+    aspectRatio     — optional, e.g. "16 / 9"
+    previewImage    — optional, URL of self-hosted preview image
+    heading         — optional, plain heading text
+    contentHtml     — required, markup to defer (placed inside <template>)
+    fallbackHref    — optional
+    fallbackText    — optional
+    attributes      — optional extra host attributes
+#}
+<mds-consent-gate
+  {% if params.category %}category="{{params.category}}"{% endif %}
+  {% if params.i18n is defined %}i18n="{{ params.i18n | dump }}"{% endif %}
+  {% if params.aspectRatio %}aspect-ratio="{{params.aspectRatio}}"{% endif %}
+  {% if params.previewImage %}preview-image="{{params.previewImage}}"{% endif %}
+  {{- MdsAttributes(params.attributes) -}}
+>
+  {% if params.heading %}<span slot="heading">{{params.heading}}</span>{% endif %}
+  <template>
+    {{ params.contentHtml | default('') | safe }}
+  </template>
+  {% if params.fallbackHref and params.fallbackText %}
+    <a slot="fallback" href="{{params.fallbackHref}}">{{params.fallbackText}}</a>
+  {% endif %}
+</mds-consent-gate>

package/src/components/consent-gate/_template.njk

@@ -0,0 +1,14 @@
+<mds-consent-gate
+  {% if category %}category="{{category}}"{% endif %}
+  {% if i18n is defined %}i18n="{{ i18n | dump }}"{% endif %}
+  {% if aspectRatio %}aspect-ratio="{{aspectRatio}}"{% endif %}
+  {% if previewImage %}preview-image="{{previewImage}}"{% endif %}
+>
+  {% if heading %}<span slot="heading">{{heading}}</span>{% endif %}
+  <template>
+    {{ contentHtml | default('') | safe }}
+  </template>
+  {% if fallbackHref and fallbackText %}
+    <a slot="fallback" href="{{fallbackHref}}">{{fallbackText}}</a>
+  {% endif %}
+</mds-consent-gate>

package/src/components/consent-gate/consent-gate-standalone.scss

@@ -0,0 +1,2 @@
+/* relying on purgecss to remove unused css */
+@import '../../scss/index.scss';

package/src/components/consent-gate/consent-gate.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  title: 'Consent Gate',
+  label: 'Consent Gate',
+  status: 'ready',
+  context: {},
+};