@codeforamerica/marcomms-design-system 1.21.2 → 1.22.0

package/src/components/carousel.test.js

@@ -0,0 +1,177 @@
+import { describe, it, expect, vi } from "vitest";
+
+// Register the custom element once for the test runtime.
+import "./carousel";
+
+// Produces a full matchMedia-like object shape used by component code.
+// Keeping this helper centralized makes reduced-motion tests explicit and readable.
+function createMatchMediaResult(matches) {
+  return {
+    matches,
+    media: "(prefers-reduced-motion: reduce)",
+    onchange: null,
+    addListener: () => {},
+    removeListener: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => false,
+  };
+}
+
+// Lit + slotchange initialization in this component involves async phases:
+// 1) initial render
+// 2) slotchange debounce
+// 3) follow-up updates
+// This helper waits through those phases so assertions target stable DOM state.
+async function waitForCarouselReady(carousel) {
+  await carousel.updateComplete;
+  await new Promise((resolve) => setTimeout(resolve, 75));
+  await carousel.updateComplete;
+}
+
+// Creates a minimal carousel fixture with plain div slides.
+// Using simple slides keeps these tests focused on carousel behavior itself.
+async function createCarouselFixture({
+  slideCount = 5,
+  itemsPerView = 2,
+  autoPlayDuration = 250,
+  reducedMotion = false,
+} = {}) {
+  const originalMatchMedia = window.matchMedia;
+
+  // Set reduced-motion mode before constructing the element,
+  // because the constructor reads matchMedia immediately.
+  window.matchMedia = vi.fn().mockImplementation(() => {
+    return createMatchMediaResult(reducedMotion);
+  });
+
+  const carousel = document.createElement("cfa-carousel");
+  carousel.setAttribute("items-per-view", String(itemsPerView));
+  carousel.autoPlayDuration = autoPlayDuration;
+
+  for (let index = 0; index < slideCount; index += 1) {
+    const slide = document.createElement("div");
+    slide.textContent = `Slide ${index + 1}`;
+    slide.setAttribute("data-test-slide", String(index));
+    carousel.appendChild(slide);
+  }
+
+  document.body.appendChild(carousel);
+  await waitForCarouselReady(carousel);
+
+  // Restore the original global to avoid leaking state into other tests.
+  window.matchMedia = originalMatchMedia;
+
+  return carousel;
+}
+
+function getVisibleSlideIndexes(carousel) {
+  return [...carousel.querySelectorAll("[data-slide-active]")].map((element) => {
+    return Number(element.getAttribute("data-test-slide"));
+  });
+}
+
+describe("cfa-carousel", () => {
+  it("initializes pagination and marks the first page of slides as active", async () => {
+    const carousel = await createCarouselFixture({ slideCount: 5, itemsPerView: 2 });
+
+    // With 5 slides and 2 per page, we expect 3 pages.
+    expect(carousel.totalSlides).toBe(5);
+    expect(carousel.totalPages).toBe(3);
+    expect(carousel.currentPage).toBe(0);
+
+    // Page 1 should show slide indexes 0 and 1.
+    expect(getVisibleSlideIndexes(carousel)).toEqual([0, 1]);
+
+    // Pagination controls should render one dot per page.
+    const dots = carousel.shadowRoot.querySelectorAll(".carousel-dot");
+    expect(dots.length).toBe(3);
+    expect(dots[0].getAttribute("aria-current")).toBe("true");
+  });
+
+  it("moves forward and backward with control buttons, including wrap-around", async () => {
+    const carousel = await createCarouselFixture({ slideCount: 5, itemsPerView: 2 });
+
+    const previousButton = carousel.shadowRoot.querySelector("button[aria-label='Previous page']");
+    const nextButton = carousel.shadowRoot.querySelector("button[aria-label='Next page']");
+
+    // Move forward once: page 0 -> page 1 (slides 2 and 3).
+    nextButton.click();
+    await carousel.updateComplete;
+    expect(carousel.currentPage).toBe(1);
+    expect(getVisibleSlideIndexes(carousel)).toEqual([2, 3]);
+
+    // Move backward once: page 1 -> page 0 (slides 0 and 1).
+    previousButton.click();
+    await carousel.updateComplete;
+    expect(carousel.currentPage).toBe(0);
+    expect(getVisibleSlideIndexes(carousel)).toEqual([0, 1]);
+
+    // Move backward at page 0 should wrap to last page (page 2, slide 4 only).
+    previousButton.click();
+    await carousel.updateComplete;
+    expect(carousel.currentPage).toBe(2);
+    expect(getVisibleSlideIndexes(carousel)).toEqual([4]);
+  });
+
+  it("jumps to a specific page when a pagination dot is clicked", async () => {
+    const carousel = await createCarouselFixture({ slideCount: 5, itemsPerView: 2 });
+
+    const dots = carousel.shadowRoot.querySelectorAll(".carousel-dot");
+
+    // Click the final dot (page index 2).
+    dots[2].click();
+    await carousel.updateComplete;
+
+    expect(carousel.currentPage).toBe(2);
+    expect(getVisibleSlideIndexes(carousel)).toEqual([4]);
+    expect(dots[2].getAttribute("aria-current")).toBe("true");
+  });
+
+  it("pauses and resumes autoplay by clearing and recreating timers", async () => {
+    const carousel = await createCarouselFixture({
+      slideCount: 5,
+      itemsPerView: 2,
+      autoPlayDuration: 200,
+      reducedMotion: false,
+    });
+
+    // Initialization starts autoplay when reduced-motion is not requested.
+    expect(carousel.isPaused).toBe(false);
+    expect(carousel.autoPlayTimer).toBeTruthy();
+    expect(carousel.autoPlayTimeout).toBeTruthy();
+
+    // Pause should fully stop autoplay and clear timer handles.
+    carousel.pause();
+    expect(carousel.isPaused).toBe(true);
+    expect(carousel.autoPlayTimer).toBeNull();
+    expect(carousel.autoPlayTimeout).toBeNull();
+
+    // Play should re-enable autoplay and recreate timer handles.
+    carousel.play();
+    expect(carousel.isPaused).toBe(false);
+    expect(carousel.autoPlayTimer).toBeTruthy();
+    expect(carousel.autoPlayTimeout).toBeTruthy();
+  });
+
+  it("disables autoplay when reduced motion is preferred", async () => {
+    const carousel = await createCarouselFixture({
+      slideCount: 5,
+      itemsPerView: 2,
+      autoPlayDuration: 200,
+      reducedMotion: true,
+    });
+
+    // Reduced motion mode should prevent autoplay from starting.
+    expect(carousel.prefersReducedMotion).toBe(true);
+    expect(carousel.isPaused).toBe(true);
+    expect(carousel.autoPlayTimer).toBeNull();
+    expect(carousel.autoPlayTimeout).toBeNull();
+
+    // Calling play() should still respect reduced motion and stay paused.
+    carousel.play();
+    expect(carousel.isPaused).toBe(true);
+    expect(carousel.autoPlayTimer).toBeNull();
+    expect(carousel.autoPlayTimeout).toBeNull();
+  });
+});

package/src/components/form-elements.stories.js

@@ -18,8 +18,11 @@ const Template = () => html`
         </div>
       </div>
       <div class="cfa-form-group">
+        <label for="single-select-example" class="cfa-label"
+          >Choose one option</label
+        >
         <div class="cfa-input-container">
-          <select class="cfa-select">
+          <select id="single-select-example" class="cfa-select">
             <option value="" disabled selected>Select your option</option>
             <option value="1">Option 1</option>
             <option value="2">Option 2</option>
@@ -27,8 +30,11 @@ const Template = () => html`
         </div>
       </div>
       <div class="cfa-form-group">
+        <label for="multi-select-example" class="cfa-label"
+          >Choose one or more options</label
+        >
         <div class="cfa-input-container">
-          <select class="cfa-multiselect" multiple>
+          <select id="multi-select-example" class="cfa-multiselect" multiple>
             <option value="" disabled selected>Select your option</option>
             <option value="1">Option 1</option>
             <option value="2">Option 2</option>

package/src/components/label.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect } from "vitest";
+import { axe } from "vitest-axe";
+
+import "./label";
+
+async function createLabelFixture() {
+  document.body.innerHTML = `
+    <cfa-label color="green">News</cfa-label>
+  `;
+
+  const label = document.querySelector("cfa-label");
+  await label.updateComplete;
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  return label;
+}
+
+async function runAxe(container) {
+  return axe(container, {
+    rules: {
+      "color-contrast": { enabled: false },
+    },
+  });
+}
+
+describe("cfa-label", () => {
+  it("renders label text and applies color attribute", async () => {
+    const label = await createLabelFixture();
+
+    const rootLabel = label.shadowRoot.querySelector(".label");
+    const slot = rootLabel.querySelector("slot");
+
+    expect(slot).toBeTruthy();
+    expect(label.textContent.trim()).toBe("News");
+    expect(rootLabel.getAttribute("color")).toBe("green");
+  });
+
+  it("has no unexpected accessibility violations", async () => {
+    const label = await createLabelFixture();
+    const results = await runAxe(label);
+
+    expect(results.violations).toHaveLength(0);
+  });
+});

package/src/components/link-list.scss

@@ -8,7 +8,7 @@ ul.is-style-link-list, /* WordPress list style class */
   --border-hover-color: var(--purple-60);
   --text-color: var(--black);
   --text-hover-color: var(--purple-80);
-  --icon-color: var(--gray-40);
+  --icon-color: var(--gray-60);
   --icon-hover-color: var(--purple-60);
   
   list-style: none;

package/src/components/nav.test.js

@@ -0,0 +1,50 @@
+import { describe, it, expect } from "vitest";
+
+// Register component under test.
+import "./nav";
+
+// Builds a fixture with realistic list content.
+async function createNavFixture(fontSize = "base") {
+  document.body.innerHTML = `
+    <cfa-nav fontSize="${fontSize}">
+      <ul>
+        <li><a href="#actions">Actions</a></li>
+        <li><a href="#schedule">Schedule</a></li>
+        <li><a href="#faq">FAQs</a></li>
+      </ul>
+    </cfa-nav>
+  `;
+
+  const nav = document.querySelector("cfa-nav");
+  await nav.updateComplete;
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  return nav;
+}
+
+describe("cfa-nav", () => {
+  it("clones slotted list items into the internal navigation list", async () => {
+    const nav = await createNavFixture();
+
+    const internalItems = nav.shadowRoot.querySelectorAll("nav ul li");
+
+    // Component should replicate slotted items into shadow DOM nav structure.
+    expect(internalItems.length).toBe(3);
+    expect(internalItems[0].textContent.trim()).toBe("Actions");
+    expect(internalItems[1].textContent.trim()).toBe("Schedule");
+    expect(internalItems[2].textContent.trim()).toBe("FAQs");
+  });
+
+  it("applies configured size and keeps links keyboard-focusable", async () => {
+    const nav = await createNavFixture("large");
+
+    const navElement = nav.shadowRoot.querySelector("nav");
+    const firstLink = nav.shadowRoot.querySelector("nav ul li a");
+
+    // Font size option should be reflected by data attribute contract.
+    expect(navElement.getAttribute("data-font-size")).toBe("large");
+
+    // Anchor elements should remain default keyboard stops.
+    expect(firstLink.tabIndex).toBe(0);
+  });
+});

package/src/components/pagination.test.js

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest";
+
+// Register component under test.
+import "./pagination";
+import "./icon";
+
+// Builds a pagination fixture with configurable page state.
+async function createPaginationFixture({ page = 1, totalPages = 3 } = {}) {
+  document.body.innerHTML = `
+    <cfa-pagination page="${page}" totalPages="${totalPages}" previousLabel="Previous" nextLabel="Next"></cfa-pagination>
+  `;
+
+  const pagination = document.querySelector("cfa-pagination");
+  await pagination.updateComplete;
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  return pagination;
+}
+
+describe("cfa-pagination", () => {
+  it("shows status text and only the Next button on first page", async () => {
+    const pagination = await createPaginationFixture({ page: 1, totalPages: 3 });
+
+    const status = pagination.shadowRoot.querySelector(".status");
+    const previousButton = pagination.shadowRoot.querySelector(".previous button");
+    const nextButton = pagination.shadowRoot.querySelector(".next button");
+
+    // First page should not show Previous button.
+    expect(previousButton).toBeNull();
+    expect(nextButton).toBeTruthy();
+    expect(status.textContent.trim()).toBe("Page 1 of 3");
+  });
+
+  it("emits page-change and advances when Next is clicked", async () => {
+    const pagination = await createPaginationFixture({ page: 1, totalPages: 3 });
+
+    let emittedDetail = null;
+    pagination.addEventListener("page-change", (event) => {
+      emittedDetail = event.detail;
+    });
+
+    const nextButton = pagination.shadowRoot.querySelector(".next button");
+    nextButton.click();
+    await pagination.updateComplete;
+
+    // Component should increment page and emit new page number.
+    expect(pagination.page).toBe(2);
+    expect(emittedDetail).toBe(2);
+  });
+
+  it("emits page-change and goes back when Previous is clicked", async () => {
+    const pagination = await createPaginationFixture({ page: 2, totalPages: 3 });
+
+    let emittedDetail = null;
+    pagination.addEventListener("page-change", (event) => {
+      emittedDetail = event.detail;
+    });
+
+    const previousButton = pagination.shadowRoot.querySelector(".previous button");
+    previousButton.click();
+    await pagination.updateComplete;
+
+    // Component should decrement page and emit new page number.
+    expect(pagination.page).toBe(1);
+    expect(emittedDetail).toBe(1);
+  });
+});

package/src/components/person-card.js

@@ -143,6 +143,8 @@ class PersonCard extends LitElement {
                 target="${this.linkTarget || "_self"}"
                 rel="${this.linkTarget == "_blank" ? "noopener" : nothing}"
                 class="link-overlay"
+                aria-label="View profile for ${this.name?.trim() || "this person"}"
+                title="View profile for ${this.name?.trim() || "this person"}"
                 tabindex="-1"
               >
               </a>

package/src/components/pullquote.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect } from "vitest";
+import { axe } from "vitest-axe";
+
+import "./pullquote";
+
+async function createPullquoteFixture() {
+  document.body.innerHTML = `
+    <cfa-pullquote>
+      <p>Accessible defaults reduce long-term maintenance overhead.</p>
+    </cfa-pullquote>
+  `;
+
+  const pullquote = document.querySelector("cfa-pullquote");
+  await pullquote.updateComplete;
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  return pullquote;
+}
+
+async function runAxe(container) {
+  return axe(container, {
+    rules: {
+      "color-contrast": { enabled: false },
+    },
+  });
+}
+
+describe("cfa-pullquote", () => {
+  it("renders blockquote wrapper for slotted content", async () => {
+    const pullquote = await createPullquoteFixture();
+
+    const blockquote = pullquote.shadowRoot.querySelector("blockquote");
+
+    expect(blockquote).toBeTruthy();
+    expect(pullquote.querySelector("p").textContent).toContain("Accessible defaults");
+  });
+
+  it("has no unexpected accessibility violations", async () => {
+    const pullquote = await createPullquoteFixture();
+    const results = await runAxe(pullquote);
+
+    expect(results.violations).toHaveLength(0);
+  });
+});

package/src/components/quote.test.js

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "vitest";
+import { axe } from "vitest-axe";
+
+import "./quote";
+
+async function createQuoteFixture() {
+  document.body.innerHTML = `
+    <cfa-quote>
+      <span slot="text">Design systems should improve consistency and speed.</span>
+      <span slot="attribution">Team Marcomms</span>
+    </cfa-quote>
+  `;
+
+  const quote = document.querySelector("cfa-quote");
+  await quote.updateComplete;
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  return quote;
+}
+
+async function runAxe(container) {
+  return axe(container, {
+    rules: {
+      "color-contrast": { enabled: false },
+    },
+  });
+}
+
+describe("cfa-quote", () => {
+  it("renders quote semantics and attribution slot", async () => {
+    const quote = await createQuoteFixture();
+
+    const blockquote = quote.shadowRoot.querySelector("blockquote");
+    const figcaption = quote.shadowRoot.querySelector("figcaption");
+
+    expect(blockquote).toBeTruthy();
+    expect(figcaption).toBeTruthy();
+    expect(quote.querySelector('[slot="attribution"]').textContent).toContain("Team Marcomms");
+  });
+
+  it("has no unexpected accessibility violations", async () => {
+    const quote = await createQuoteFixture();
+    const results = await runAxe(quote);
+
+    expect(results.violations).toHaveLength(0);
+  });
+});

package/src/components/reveal.test.js

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import { axe } from "vitest-axe";
+
+// Register component dependencies for this test module.
+import "./reveal";
+import "./icon";
+
+// Builds a minimal reveal fixture with realistic slotted content.
+async function createRevealFixture() {
+  document.body.innerHTML = `
+    <cfa-reveal showLabel="Show more" hideLabel="Show less">
+      <p>Hidden details text</p>
+    </cfa-reveal>
+  `;
+
+  const reveal = document.querySelector("cfa-reveal");
+  await reveal.updateComplete;
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  return reveal;
+}
+
+// Runs axe with a jsdom-safe configuration.
+async function runAxe(container) {
+  return axe(container, {
+    rules: {
+      "color-contrast": { enabled: false },
+    },
+  });
+}
+
+describe("cfa-reveal", () => {
+  it("toggles expanded state and button label on click", async () => {
+    const reveal = await createRevealFixture();
+
+    const button = reveal.shadowRoot.querySelector("button");
+    const slot = reveal.shadowRoot.querySelector("slot#content");
+
+    // Initial state should be collapsed.
+    expect(reveal.expanded).toBe(false);
+    expect(button.getAttribute("aria-expanded")).toBe("false");
+    expect(button.textContent).toContain("Show more");
+    expect(slot.hidden).toBe(true);
+
+    // Clicking should expand and update visible control text/state.
+    button.click();
+    await reveal.updateComplete;
+
+    expect(reveal.expanded).toBe(true);
+    expect(button.getAttribute("aria-expanded")).toBe("true");
+    expect(button.textContent).toContain("Show less");
+    expect(slot.hidden).toBe(false);
+  });
+
+  it("has no unexpected accessibility violations", async () => {
+    const reveal = await createRevealFixture();
+    const results = await runAxe(reveal);
+
+    expect(results.violations).toHaveLength(0);
+  });
+});

package/src/components/slide.stories.js

@@ -43,7 +43,3 @@ Default.args = {
   linkUrl: "#",
 };
 
-export const SlideWithoutImage = Template.bind({});
-SlideWithoutImage.args = {
-  linkUrl: "#",
-};

package/src/components/tab-list.a11y.test.js

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "vitest";
+import { axe } from "vitest-axe";
+
+// Register components so fixtures can instantiate custom elements.
+import "./tab-list";
+import "./tab";
+
+// Creates a representative tab interface with explicit panel links.
+// This mirrors realistic component usage and gives axe meaningful semantics to inspect.
+async function createA11yFixture() {
+  document.body.innerHTML = `
+    <section aria-label="News tabs example">
+      <cfa-tab-list>
+        <cfa-tab id="tab-overview" panelid="panel-overview">Overview</cfa-tab>
+        <cfa-tab id="tab-updates" panelid="panel-updates">Updates</cfa-tab>
+        <cfa-tab id="tab-events" panelid="panel-events">Events</cfa-tab>
+      </cfa-tab-list>
+
+      <div id="panel-overview" role="tabpanel" aria-labelledby="tab-overview">Overview content</div>
+      <div id="panel-updates" role="tabpanel" aria-labelledby="tab-updates">Updates content</div>
+      <div id="panel-events" role="tabpanel" aria-labelledby="tab-events">Events content</div>
+    </section>
+  `;
+
+  const tabList = document.querySelector("cfa-tab-list");
+  await tabList.updateComplete;
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  return tabList;
+}
+
+// Runs axe with a jsdom-safe configuration.
+// The color-contrast rule depends on canvas APIs not implemented in jsdom,
+// so we disable that single rule in unit tests and keep semantic checks active.
+async function runAxe(container) {
+  return axe(container, {
+    rules: {
+      "color-contrast": { enabled: false },
+    },
+  });
+}
+
+describe("cfa-tab-list accessibility", () => {
+  it("applies expected tab semantics and ARIA state on startup", async () => {
+    const tabList = await createA11yFixture();
+    const tabs = [...tabList.querySelectorAll("cfa-tab")];
+
+    // Parent tablist semantics are required for assistive technologies.
+    expect(tabList.getAttribute("role")).toBe("tablist");
+
+    // Roving tabindex and selected state should start on the first tab.
+    expect(tabs[0].getAttribute("aria-selected")).toBe("true");
+    expect(tabs[0].getAttribute("tabindex")).toBe("0");
+
+    // Remaining tabs should be inactive until user interaction.
+    expect(tabs[1].getAttribute("aria-selected")).toBe("false");
+    expect(tabs[1].getAttribute("tabindex")).toBe("-1");
+    expect(tabs[2].getAttribute("aria-selected")).toBe("false");
+    expect(tabs[2].getAttribute("tabindex")).toBe("-1");
+  });
+
+  it("maintains a predictable roving focus order when active tab changes", async () => {
+    const tabList = await createA11yFixture();
+    const tabs = [...tabList.querySelectorAll("cfa-tab")];
+
+    // Before interaction, first tab should be the only keyboard stop.
+    expect(tabs[0].getAttribute("tabindex")).toBe("0");
+    expect(tabs[1].getAttribute("tabindex")).toBe("-1");
+    expect(tabs[2].getAttribute("tabindex")).toBe("-1");
+
+    // After activating the second tab, focus order should move with it.
+    tabs[1].click();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(tabs[0].getAttribute("tabindex")).toBe("-1");
+    expect(tabs[1].getAttribute("tabindex")).toBe("0");
+    expect(tabs[2].getAttribute("tabindex")).toBe("-1");
+
+  });
+
+  it("has no unexpected accessibility violations for tab and tabpanel structure", async () => {
+    const tabList = await createA11yFixture();
+    const results = await runAxe(tabList.parentElement);
+
+    expect(results.violations).toHaveLength(0);
+  });
+});