@madgex/design-system 13.6.4 → 13.7.0

package/src/components/scroll-spy/scroll-spy.spec.js

@@ -0,0 +1,462 @@
+// eslint-disable-next-line n/no-unpublished-import
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { MdsScrollSpy } from './scroll-spy.js';
+
+// Polyfill CSS.escape for jsdom (not available by default)
+if (typeof CSS === 'undefined' || !CSS.escape) {
+  globalThis.CSS = {
+    escape: (str) => str.replace(/([^\w-])/g, (match) => `\\${match}`),
+  };
+}
+
+// Mock IntersectionObserver
+let lastObserverInstance = null;
+
+class MockIntersectionObserver {
+  constructor(callback, options) {
+    this.callback = callback;
+    this.options = options;
+    this.observedElements = [];
+    lastObserverInstance = this;
+  }
+  observe(el) {
+    this.observedElements.push(el);
+  }
+  unobserve(el) {
+    this.observedElements = this.observedElements.filter((e) => e !== el);
+  }
+  disconnect() {
+    this.observedElements = [];
+  }
+  // Helper to simulate intersection events
+  triggerIntersect(entries) {
+    this.callback(entries, this);
+  }
+}
+
+vi.stubGlobal('IntersectionObserver', MockIntersectionObserver);
+
+// Register the custom element
+if (!customElements.get('mds-scroll-spy')) {
+  customElements.define('mds-scroll-spy', MdsScrollSpy);
+}
+
+describe('MdsScrollSpy', () => {
+  let container;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    container.remove();
+    vi.restoreAllMocks();
+  });
+
+  /**
+   * Helper to create a scroll-spy and attach it to the container with links.
+   * Uses innerHTML to ensure proper URL resolution in jsdom.
+   */
+  function createScrollSpyWithLinks(anchors) {
+    const linksHtml = anchors.map(({ href, text }) => `<a href="${href}">${text}</a>`).join('');
+    container.innerHTML = `<mds-scroll-spy>${linksHtml}</mds-scroll-spy>`;
+    return container.querySelector('mds-scroll-spy');
+  }
+
+  // ------------------------------
+  // Constructor
+  // ------------------------------
+  describe('constructor', () => {
+    it('creates instance without errors', () => {
+      const scrollSpy = new MdsScrollSpy();
+      expect(scrollSpy).toBeInstanceOf(MdsScrollSpy);
+      expect(scrollSpy).toBeInstanceOf(HTMLElement);
+    });
+  });
+
+  // ------------------------------
+  // observer-threshold attribute parsing (tested via behavior)
+  // ------------------------------
+  describe('observer-threshold attribute', () => {
+    it('accepts single numeric threshold value', () => {
+      const section = document.createElement('section');
+      section.id = 'test-section';
+      document.body.appendChild(section);
+
+      container.innerHTML = `
+        <mds-scroll-spy observer-threshold="0.5">
+          <a href="#test-section">Link</a>
+        </mds-scroll-spy>
+      `;
+      const scrollSpy = container.querySelector('mds-scroll-spy');
+
+      // Element should initialize without errors
+      expect(scrollSpy).toBeInstanceOf(MdsScrollSpy);
+
+      section.remove();
+    });
+
+    it('accepts JSON array threshold value', () => {
+      const section = document.createElement('section');
+      section.id = 'test-section';
+      document.body.appendChild(section);
+
+      container.innerHTML = `
+        <mds-scroll-spy observer-threshold="[0, 0.5, 1]">
+          <a href="#test-section">Link</a>
+        </mds-scroll-spy>
+      `;
+      const scrollSpy = container.querySelector('mds-scroll-spy');
+
+      expect(scrollSpy).toBeInstanceOf(MdsScrollSpy);
+
+      section.remove();
+    });
+
+    it('warns and uses default for invalid threshold', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const section = document.createElement('section');
+      section.id = 'test-section';
+      document.body.appendChild(section);
+
+      container.innerHTML = `
+        <mds-scroll-spy observer-threshold="invalid">
+          <a href="#test-section">Link</a>
+        </mds-scroll-spy>
+      `;
+      const scrollSpy = container.querySelector('mds-scroll-spy');
+
+      expect(scrollSpy).toBeInstanceOf(MdsScrollSpy);
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('Invalid observer-threshold'));
+
+      section.remove();
+    });
+
+    it('warns and uses default for empty array threshold', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const section = document.createElement('section');
+      section.id = 'test-section';
+      document.body.appendChild(section);
+
+      container.innerHTML = `
+        <mds-scroll-spy observer-threshold="[]">
+          <a href="#test-section">Link</a>
+        </mds-scroll-spy>
+      `;
+      const scrollSpy = container.querySelector('mds-scroll-spy');
+
+      expect(scrollSpy).toBeInstanceOf(MdsScrollSpy);
+      expect(warnSpy).toHaveBeenCalled();
+
+      section.remove();
+    });
+  });
+
+  // ------------------------------
+  // Section discovery (via links)
+  // ------------------------------
+  describe('section discovery', () => {
+    it('observes sections referenced by links', () => {
+      const section1 = document.createElement('section');
+      section1.id = 'section-1';
+      const section2 = document.createElement('section');
+      section2.id = 'section-2';
+      document.body.appendChild(section1);
+      document.body.appendChild(section2);
+
+      container.innerHTML = `
+        <mds-scroll-spy>
+          <a href="#section-1">Section 1</a>
+          <a href="#section-2">Section 2</a>
+        </mds-scroll-spy>
+      `;
+      const scrollSpy = container.querySelector('mds-scroll-spy');
+
+      // Verify observer was created and is observing sections
+      expect(scrollSpy).toBeInstanceOf(MdsScrollSpy);
+
+      section1.remove();
+      section2.remove();
+    });
+
+    it('warns when section element does not exist', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      createScrollSpyWithLinks([{ href: '#nonexistent', text: 'Link' }]);
+
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("doesn't exist on this page"));
+    });
+
+    it('ignores external links', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      container.innerHTML = `
+        <mds-scroll-spy>
+          <a href="https://external.com/page#section">External</a>
+        </mds-scroll-spy>
+      `;
+
+      // No warning should be logged for external links
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it('ignores links without hash', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      container.innerHTML = `
+        <mds-scroll-spy>
+          <a href="/page">No hash</a>
+        </mds-scroll-spy>
+      `;
+
+      // No warning should be logged for links without hash
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it('handles IDs with special characters', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const section = document.createElement('section');
+      section.id = 'section:with.special-chars';
+      document.body.appendChild(section);
+
+      createScrollSpyWithLinks([{ href: '#section:with.special-chars', text: 'Special' }]);
+
+      // No warning means section was found
+      expect(warnSpy).not.toHaveBeenCalled();
+
+      section.remove();
+    });
+  });
+
+  // ------------------------------
+  // Observer options (via attributes)
+  // ------------------------------
+  describe('observer options', () => {
+    it('uses default threshold when no attribute provided', () => {
+      const section = document.createElement('section');
+      section.id = 'test-section';
+      document.body.appendChild(section);
+
+      container.innerHTML = `
+        <mds-scroll-spy>
+          <a href="#test-section">Link</a>
+        </mds-scroll-spy>
+      `;
+      const scrollSpy = container.querySelector('mds-scroll-spy');
+
+      // Check that observer was created (via mock)
+      expect(scrollSpy).toBeInstanceOf(MdsScrollSpy);
+
+      section.remove();
+    });
+
+    it('uses observer-root attribute', () => {
+      const rootEl = document.createElement('div');
+      rootEl.id = 'scroll-root';
+      document.body.appendChild(rootEl);
+
+      const section = document.createElement('section');
+      section.id = 'test-section';
+      rootEl.appendChild(section);
+
+      container.innerHTML = `
+        <mds-scroll-spy observer-root="#scroll-root">
+          <a href="#test-section">Link</a>
+        </mds-scroll-spy>
+      `;
+      const scrollSpy = container.querySelector('mds-scroll-spy');
+
+      expect(scrollSpy).toBeInstanceOf(MdsScrollSpy);
+
+      rootEl.remove();
+    });
+
+    it('uses observer-threshold attribute', () => {
+      const section = document.createElement('section');
+      section.id = 'test-section';
+      document.body.appendChild(section);
+
+      container.innerHTML = `
+        <mds-scroll-spy observer-threshold="0.75">
+          <a href="#test-section">Link</a>
+        </mds-scroll-spy>
+      `;
+      const scrollSpy = container.querySelector('mds-scroll-spy');
+
+      expect(scrollSpy).toBeInstanceOf(MdsScrollSpy);
+
+      section.remove();
+    });
+  });
+
+  // ------------------------------
+  // connectedCallback
+  // ------------------------------
+  describe('connectedCallback', () => {
+    it('finds links within the element', () => {
+      container.innerHTML = `
+        <mds-scroll-spy>
+          <a href="#a">A</a>
+          <a href="#b">B</a>
+        </mds-scroll-spy>
+      `;
+
+      const scrollSpy = container.querySelector('mds-scroll-spy');
+      const links = scrollSpy.querySelectorAll('a');
+      expect(links).toHaveLength(2);
+    });
+
+    it('uses aria-current-value attribute when setting active state', () => {
+      const section = document.createElement('section');
+      section.id = 'test';
+      document.body.appendChild(section);
+
+      container.innerHTML = `
+        <mds-scroll-spy aria-current-value="location">
+          <a href="#test">Test</a>
+        </mds-scroll-spy>
+      `;
+
+      const scrollSpy = container.querySelector('mds-scroll-spy');
+      expect(scrollSpy.getAttribute('aria-current-value')).toBe('location');
+
+      section.remove();
+    });
+
+    it('does not create observer when no sections found', () => {
+      vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      container.innerHTML = `
+        <mds-scroll-spy>
+          <a href="#nonexistent">Link</a>
+        </mds-scroll-spy>
+      `;
+
+      // Element should still be created without errors
+      const scrollSpy = container.querySelector('mds-scroll-spy');
+      expect(scrollSpy).toBeInstanceOf(MdsScrollSpy);
+    });
+
+    it('creates observer when sections exist', () => {
+      const section = document.createElement('section');
+      section.id = 'test-section';
+      document.body.appendChild(section);
+
+      const scrollSpy = createScrollSpyWithLinks([{ href: '#test-section', text: 'Link' }]);
+
+      expect(scrollSpy).toBeInstanceOf(MdsScrollSpy);
+
+      section.remove();
+    });
+  });
+
+  // ------------------------------
+  // disconnectedCallback
+  // ------------------------------
+  describe('disconnectedCallback', () => {
+    it('cleans up without errors when removed', () => {
+      const section = document.createElement('section');
+      section.id = 'cleanup-test';
+      document.body.appendChild(section);
+
+      const scrollSpy = createScrollSpyWithLinks([{ href: '#cleanup-test', text: 'Link' }]);
+
+      // Should not throw when removing
+      expect(() => scrollSpy.remove()).not.toThrow();
+
+      section.remove();
+    });
+
+    it('handles disconnect when no observer was created', () => {
+      container.innerHTML = `<mds-scroll-spy></mds-scroll-spy>`;
+      const scrollSpy = container.querySelector('mds-scroll-spy');
+
+      // Should not throw
+      expect(() => scrollSpy.remove()).not.toThrow();
+    });
+  });
+
+  // ------------------------------
+  // setObserver / aria-current behavior
+  // ------------------------------
+  describe('setObserver', () => {
+    it('sets up intersection observer for sections', () => {
+      const section = document.createElement('section');
+      section.id = 'observer-test';
+      document.body.appendChild(section);
+
+      container.innerHTML = `
+        <mds-scroll-spy observer-threshold="0.5">
+          <a href="#observer-test">Link</a>
+        </mds-scroll-spy>
+      `;
+      const scrollSpy = container.querySelector('mds-scroll-spy');
+
+      expect(scrollSpy).toBeInstanceOf(MdsScrollSpy);
+
+      section.remove();
+    });
+
+    it('sets aria-current on most visible section link', () => {
+      const section1 = document.createElement('section');
+      section1.id = 'section-1';
+      const section2 = document.createElement('section');
+      section2.id = 'section-2';
+      document.body.appendChild(section1);
+      document.body.appendChild(section2);
+
+      container.innerHTML = `
+        <mds-scroll-spy>
+          <a href="#section-1">Section 1</a>
+          <a href="#section-2">Section 2</a>
+        </mds-scroll-spy>
+      `;
+      const scrollSpy = container.querySelector('mds-scroll-spy');
+      const link1 = scrollSpy.querySelector('a[href="#section-1"]');
+      const link2 = scrollSpy.querySelector('a[href="#section-2"]');
+
+      // Verify initial state (no aria-current)
+      expect(link1.getAttribute('aria-current')).toBeNull();
+      expect(link2.getAttribute('aria-current')).toBeNull();
+
+      // Simulate intersection: section-1 is more visible
+      lastObserverInstance.triggerIntersect([
+        { target: section1, intersectionRatio: 0.8 },
+        { target: section2, intersectionRatio: 0.2 },
+      ]);
+
+      expect(link1.getAttribute('aria-current')).toBe('step');
+      expect(link2.getAttribute('aria-current')).toBeNull();
+
+      // Simulate scrolling: section-2 becomes more visible
+      lastObserverInstance.triggerIntersect([
+        { target: section1, intersectionRatio: 0.1 },
+        { target: section2, intersectionRatio: 0.9 },
+      ]);
+
+      expect(link1.getAttribute('aria-current')).toBeNull();
+      expect(link2.getAttribute('aria-current')).toBe('step');
+
+      section1.remove();
+      section2.remove();
+    });
+
+    it('uses custom aria-current-value attribute', () => {
+      const section = document.createElement('section');
+      section.id = 'custom-aria';
+      document.body.appendChild(section);
+
+      container.innerHTML = `
+        <mds-scroll-spy aria-current-value="page">
+          <a href="#custom-aria">Link</a>
+        </mds-scroll-spy>
+      `;
+      const scrollSpy = container.querySelector('mds-scroll-spy');
+
+      expect(scrollSpy.getAttribute('aria-current-value')).toBe('page');
+
+      section.remove();
+    });
+  });
+});

package/src/js/index.js

@@ -15,6 +15,7 @@ import { MdsCardLink } from '../components/card/card-link';
 import { MdsConditionalSection } from '../components/conditional-section/conditional-section';
 import { MdsImageCropper } from '../components/image-cropper/image-cropper';
 import { MdsCategoryPicker } from '../components/inputs/category-picker/category-picker';
+import { MdsScrollSpy } from '../components/scroll-spy/scroll-spy';
 
 if (!window.customElements.get('mds-dropdown-nav')) {
   window.customElements.define('mds-dropdown-nav', MdsDropdownNav);
@@ -37,6 +38,9 @@ if (!window.customElements.get('mds-file-upload')) {
 if (!window.customElements.get('mds-category-picker')) {
   window.customElements.define('mds-category-picker', MdsCategoryPicker);
 }
+if (!window.customElements.get('mds-scroll-spy')) {
+  window.customElements.define('mds-scroll-spy', MdsScrollSpy);
+}
 
 const initAll = () => {
   tabs.init();

package/src/scss/core/_lists.scss

@@ -126,5 +126,26 @@
         color: $constant-color-neutral-light;
       }
     }
+
+    &.mds-step-list__item--has-subnav:before {
+      margin-bottom: 0;
+    }
   }
 }
+
+.mds-step-list-subnav {
+  list-style-type: none;
+  border-left: 1px solid $constant-color-neutral-light;
+  margin-left: 1.25em;
+}
+.mds-step-list-subnav__link {
+  display: block;
+  padding: $constant-size-baseline * 5;
+  font-weight: normal;
+  border-left: 4px solid transparent;
+
+  &[aria-current] {
+    color: var(--mds-color-text-base);
+    border-left-color: $link-color;
+  }
+}

package/src/scss/helpers/__index.scss

@@ -12,3 +12,4 @@
 @import 'text-formatting';
 @import 'table';
 @import 'container-queries';
+@import 'position';

package/src/scss/helpers/_position.scss

@@ -0,0 +1,4 @@
+.mds-position-sticky {
+  position: sticky;
+  top: $constant-size-baseline * 5;
+}

package/src/typography/lists.njk

@@ -10,14 +10,12 @@
     <a href="#three">three</a>
   </li>
 </ul>
-
 <h2>Ordered list</h2>
 <ol class="mds-list mds-list--number">
   <li class="mds-list__item">one</li>
   <li class="mds-list__item">two</li>
   <li class="mds-list__item">three</li>
 </ol>
-
 <h2>Definition List with border</h2>
 <dl class="mds-list mds-list--definition mds-list--border">
   <dt class="mds-list__key">Recruiter</dt>
@@ -27,21 +25,18 @@
   <dt class="mds-list__key">Expires</dt>
   <dd class="mds-list__value">12pm, 25th November 1983</dd>
 </dl>
-
 <h2>Inline list</h2>
 <ul class="mds-list mds-list--inline">
   <li class="mds-list__item">One</li>
   <li class="mds-list__item">Two</li>
   <li class="mds-list__item">Three</li>
 </ul>
-
 <h2>Bordered inline list (separated)</h2>
 <ul class="mds-list mds-list--inline mds-list--pipe">
   <li class="mds-list__item">Four</li>
   <li class="mds-list__item">Five</li>
   <li class="mds-list__item">Six</li>
 </ul>
-
 <h2>Multilevel list</h2>
 <ol class="mds-list mds-list--number mds-list--multilevel">
   <li class="mds-list__item">
@@ -54,7 +49,13 @@
     <ul class="mds-list mds-list--bullet">
       <li class="mds-list__item">first</li>
       <li class="mds-list__item">second</li>
-      <li class="mds-list__item">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent eget metus nisi. Morbi sollicitudin, erat sed elementum suscipit, dolor nibh sagittis dui, at ultrices massa erat non ipsum. Nam euismod dapibus augue, sit amet efficitur urna malesuada vitae. Sed tincidunt felis a turpis vulputate, vitae sodales nibh imperdiet. Donec ullamcorper risus quis convallis mollis. Nullam nec magna lectus. Etiam in lobortis purus. Duis vestibulum, nibh sit amet commodo porttitor, nunc metus eleifend magna, at venenatis tortor justo at eros. Vivamus eu tincidunt mi, vel fermentum tortor. Aenean tempus, magna a scelerisque consequat, libero tortor porttitor neque, nec aliquam lorem purus sodales diam. Pellentesque a orci vitae orci fringilla sollicitudin quis vitae leo.
+      <li class="mds-list__item">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent eget metus nisi. Morbi
+        sollicitudin, erat sed elementum suscipit, dolor nibh sagittis dui, at ultrices massa erat non ipsum. Nam euismod
+        dapibus augue, sit amet efficitur urna malesuada vitae. Sed tincidunt felis a turpis vulputate, vitae sodales nibh
+        imperdiet. Donec ullamcorper risus quis convallis mollis. Nullam nec magna lectus. Etiam in lobortis purus. Duis
+        vestibulum, nibh sit amet commodo porttitor, nunc metus eleifend magna, at venenatis tortor justo at eros. Vivamus eu
+        tincidunt mi, vel fermentum tortor. Aenean tempus, magna a scelerisque consequat, libero tortor porttitor neque, nec
+        aliquam lorem purus sodales diam. Pellentesque a orci vitae orci fringilla sollicitudin quis vitae leo.
         <ul class="mds-list mds-list--bullet">
           <li class="mds-list__item">once</li>
           <li class="mds-list__item">twice</li>
@@ -69,7 +70,6 @@
     <a href="#two">five</a>
   </li>
 </ol>
-
 <h2>List with no indent</h2>
 <ul class="mds-list mds-list--bullet mds-list--noindent">
   <li class="mds-list__item">
@@ -82,17 +82,30 @@
     <a href="#three">three</a>
   </li>
 </ul>
-
 <h2>Step List</h2>
 <ol class="mds-step-list">
   <li class="mds-step-list__item">Step 1</li>
   <li class="mds-step-list__item">Step 2</li>
   <li class="mds-step-list__item">Step 3</li>
 </ol>
-
 <h2>Step List with page progress</h2>
 <ol class="mds-step-list">
-  <li class="mds-step-list__item"><a href="https://www.google.com">Past page with link</a></li>
-  <li class="mds-step-list__item mds-step-list__item--current" aria-current="page">Current page</li>
+  <li class="mds-step-list__item">
+    <a href="https://www.google.com">Past page with link</a>
+  </li>
+  <li class="mds-step-list__item mds-step-list__item--current mds-step-list__item--has-subnav" aria-current="page">Current
+    page
+    <ul class="mds-step-list-subnav">
+      <li class="mds-step-list-subnav__item">
+        <a class="mds-step-list-subnav__link" href="#section-1">Section 1</a>
+      </li>
+      <li class="mds-step-list-subnav__item">
+        <a class="mds-step-list-subnav__link" href="#section-2" aria-current="location">Section 2</a>
+      </li>
+      <li class="mds-step-list-subnav__item">
+        <a class="mds-step-list-subnav__link" href="#section-3">Section 3</a>
+      </li>
+    </ul>
+  </li>
   <li class="mds-step-list__item mds-step-list__item--future">Ghost of pages future</li>
 </ol>