decidim-core 0.30.1 → 0.31.0.rc1

data/app/packs/src/decidim/controllers/toggle/toggle.test.js

@@ -0,0 +1,260 @@
+/* global jest */
+
+import { Application } from "@hotwired/stimulus";
+import ToggleController from "src/decidim/controllers/toggle/controller";
+
+describe("ToggleController", () => {
+  let application = null;
+  let controller = null;
+  let element = null;
+  let targetElement1 = null;
+  let targetElement2 = null;
+
+  beforeEach(() => {
+    // Set up the DOM
+    document.body.innerHTML = `
+      <button
+        data-controller="toggle"
+        data-toggle-toggle-value="target1 target2"
+      >
+        Toggle Button
+      </button>
+      <div id="target1" hidden>Target 1 Content</div>
+      <div id="target2" hidden>Target 2 Content</div>
+    `;
+
+    // Set up Stimulus application
+    application = Application.start();
+    application.register("toggle", ToggleController);
+
+    element = document.querySelector('[data-controller="toggle"]');
+    targetElement1 = document.getElementById("target1");
+    targetElement2 = document.getElementById("target2");
+
+    // Wait for the controller to be connected
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        controller = application.getControllerForElementAndIdentifier(element, "toggle")
+        resolve();
+      }, 0);
+    });
+  });
+
+  afterEach(() => {
+    application.stop();
+    document.body.innerHTML = "";
+    jest.clearAllMocks();
+  });
+
+  describe("connect", () => {
+    it("ensures the component has an ID", () => {
+      document.body.innerHTML = "";
+      const elementWithoutId = document.createElement("button");
+      elementWithoutId.setAttribute("data-controller", "toggle");
+      elementWithoutId.setAttribute("data-toggle-toggle-value", "target1");
+      document.body.appendChild(elementWithoutId);
+
+      controller.disconnect()
+      controller.connect();
+
+      expect(controller.element.id).toMatch(/^toggle-[a-z0-9]+$/);
+    });
+
+    it("sets up aria-controls attribute", () => {
+      expect(element.getAttribute("aria-controls")).toBe("target1 target2");
+    });
+
+    it("sets up aria-labelledby attributes for target elements", () => {
+      const target1LabelledBy = targetElement1.getAttribute("aria-labelledby");
+      const target2LabelledBy = targetElement2.getAttribute("aria-labelledby");
+
+      expect(target1LabelledBy).toContain(element.id);
+      expect(target2LabelledBy).toContain(element.id);
+    });
+
+    it("binds click event listener", () => {
+      const spy = jest.spyOn(controller, "handleToggle");
+      element.click();
+      expect(spy).toHaveBeenCalled();
+    });
+
+    it("preserves existing aria-labelledby values", () => {
+      const existingLabel = "existing-label";
+      targetElement1.setAttribute("aria-labelledby", existingLabel);
+
+      // Re-initialize controller
+      application.stop();
+      application = Application.start();
+      application.register("toggle", ToggleController);
+      controller = application.getControllerForElementAndIdentifier(element, "toggle");
+
+      const labelledBy = targetElement1.getAttribute("aria-labelledby");
+      expect(labelledBy).toBe(`${existingLabel}`);
+    });
+  });
+
+  describe("disconnect", () => {
+    it("removes event listeners", () => {
+      const removeEventListenerSpy = jest.spyOn(element, "removeEventListener");
+      controller.disconnect();
+      expect(removeEventListenerSpy).toHaveBeenCalledWith("click", controller.handleToggle);
+    });
+  });
+
+  describe("handleToggle", () => {
+    beforeEach(() => {
+      // Ensure targets are initially hidden
+      targetElement1.hidden = true;
+      targetElement2.hidden = true;
+    });
+
+    it("toggles visibility of target elements", () => {
+      controller.handleToggle();
+
+      expect(targetElement1.hidden).toBe(false);
+      expect(targetElement2.hidden).toBe(false);
+    });
+
+    it("sets aria-expanded attribute correctly", () => {
+      controller.handleToggle();
+
+      expect(targetElement1.getAttribute("aria-expanded")).toBe("true");
+      expect(targetElement2.getAttribute("aria-expanded")).toBe("true");
+    });
+
+    it("toggles back to hidden state", () => {
+      // First toggle - show
+      controller.handleToggle();
+      expect(targetElement1.hidden).toBe(false);
+      expect(targetElement2.hidden).toBe(false);
+
+      // Second toggle - hide
+      controller.handleToggle();
+      expect(targetElement1.hidden).toBe(true);
+      expect(targetElement2.hidden).toBe(true);
+    });
+
+    it("handles nonexistent target elements gracefully", () => {
+      element.setAttribute("data-toggle-toggle-value", "nonexistent target1");
+
+      expect(() => {
+        controller.handleToggle();
+      }).not.toThrow();
+
+      // Should still toggle the existing element
+      expect(targetElement1.hidden).toBe(false);
+    });
+
+    it("dispatches custom toggle event", () => {
+      const eventSpy = jest.spyOn(document, "dispatchEvent");
+
+      controller.handleToggle();
+
+      expect(eventSpy).toHaveBeenCalledWith(expect.objectContaining({
+        type: "on:toggle"
+      }));
+    });
+  });
+
+  describe("getTargetIds", () => {
+    it("returns array of target IDs from space-separated string", () => {
+      const targetIds = controller.getTargetIds();
+      expect(targetIds).toEqual(["target1", "target2"]);
+    });
+
+    it("handles single target ID", () => {
+      element.setAttribute("data-toggle-toggle-value", "single-target");
+      const targetIds = controller.getTargetIds();
+      expect(targetIds).toEqual(["single-target"]);
+    });
+  });
+
+  describe("integration tests", () => {
+    it("works with click events", () => {
+      element.click();
+
+      expect(targetElement1.hidden).toBe(false);
+      expect(targetElement2.hidden).toBe(false);
+      expect(targetElement1.getAttribute("aria-expanded")).toBe("true");
+      expect(targetElement2.getAttribute("aria-expanded")).toBe("true");
+    });
+
+    it("dispatches toggle event on click", (done) => {
+      document.addEventListener("on:toggle", () => {
+        done();
+      });
+
+      element.click();
+    });
+
+    it("handles keyboard activation", () => {
+      const enterEvent = new KeyboardEvent("keydown", { key: "Enter" });
+      element.dispatchEvent(enterEvent);
+
+      // Note: This test assumes the button element handles Enter key natively
+      // which triggers a click event
+      element.click();
+
+      expect(targetElement1.hidden).toBe(false);
+      expect(targetElement2.hidden).toBe(false);
+    });
+  });
+
+  describe("accessibility features", () => {
+    it("maintains proper ARIA attributes", () => {
+      expect(element.getAttribute("aria-controls")).toBe("target1 target2");
+
+      element.click();
+
+      expect(targetElement1.getAttribute("aria-expanded")).toBe("true");
+      expect(targetElement2.getAttribute("aria-expanded")).toBe("true");
+    });
+
+    it("creates bidirectional ARIA relationships", () => {
+      const target1LabelledBy = targetElement1.getAttribute("aria-labelledby");
+      const target2LabelledBy = targetElement2.getAttribute("aria-labelledby");
+
+      expect(target1LabelledBy).toContain(element.id);
+      expect(target2LabelledBy).toContain(element.id);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("handles empty toggle value", () => {
+      element.setAttribute("data-toggle-toggle-value", "");
+
+      expect(() => {
+        controller.handleToggle();
+      }).not.toThrow();
+    });
+
+    it("handles whitespace in toggle value", () => {
+      element.setAttribute("data-toggle-toggle-value", "  target1   target2  ");
+
+      const targetIds = controller.getTargetIds();
+      expect(targetIds).toEqual(["", "", "target1", "", "", "target2", "", ""]);
+    });
+
+    it("generates unique IDs for multiple toggle elements", async () => {
+      const secondToggle = document.createElement("button");
+      secondToggle.setAttribute("data-controller", "toggle");
+      secondToggle.setAttribute("data-toggle-toggle-value", "target1");
+      document.body.appendChild(secondToggle);
+
+      controller.disconnect();
+      let secondController = null;
+
+      await new Promise((resolve) => {
+        setTimeout(() => {
+          controller = application.getControllerForElementAndIdentifier(element, "toggle");
+          secondController = application.getControllerForElementAndIdentifier(secondToggle, "toggle");
+          resolve();
+        }, 0);
+      });
+
+      expect(element.id).not.toBe(secondController.element.id);
+      expect(element.id).toMatch(/^toggle-[a-z0-9]+$/);
+      expect(secondController.element.id).toMatch(/^toggle-[a-z0-9]+$/);
+    });
+  });
+});

data/app/packs/src/decidim/controllers/tooltip/controller.js

@@ -0,0 +1,287 @@
+import { Controller } from "@hotwired/stimulus"
+
+/**
+ * Tooltip Stimulus Controller
+ *
+ * Usage:
+ * <button data-controller="tooltip" data-tooltip-tooltip-value="<div class='tooltip top'>Tooltip content</div>">
+ *   Hover me
+ * </button>
+ *
+ * Or with data attribute:
+ * <button data-controller="tooltip" data-tooltip-tooltip-value="<div class='tooltip bottom'>Content</div>">
+ *   Click me
+ * </button>
+ */
+export default class extends Controller {
+  static get values() {
+    return {
+      tooltip: String
+    }
+  }
+
+  connect() {
+    this.tooltip = null
+    this.useMobile = (/Mobi|Android/i).test(navigator.userAgent)
+    this.outsideClickHandler = this.handleOutsideClick.bind(this)
+
+
+    if (!this.tooltipValue) {
+      return
+    }
+
+    const div = document.createElement("div")
+    div.innerHTML = this.tooltipValue
+    this.tooltip = div.firstElementChild
+
+    // only run this script when the tooltip content is html
+    if (!(this.tooltip instanceof HTMLElement)) {
+      return
+    }
+
+    this.setupTooltip()
+    this.bindEvents()
+  }
+
+  disconnect() {
+    this.cleanup()
+  }
+
+  /**
+   * Returns 9 useful positions (page coordinates) of a HTMLElement regarding the window object
+   *
+   *    topLeft      topCenter      topRight
+   *           \ ________|________ /
+   *            |                 |
+   * middleLeft |   middleCenter  | middleRight
+   *            |_________________|
+   *           /         |         \
+   * bottomLeft     bottomCenter    bottomRight
+   *
+   * @param {HTMLElement} node target node
+   * @param {HTMLElement} relativeParent relative parent, instead of window
+   * @returns {Object} Nine pair of page coordinates
+   */
+  getAbsolutePosition(node, relativeParent) {
+
+    const { top, left, width, height } = node.getBoundingClientRect()
+
+    let [pageX, pageY] = [window.pageXOffset, window.pageYOffset]
+    if (relativeParent) {
+      const { topLeft: [parentX, parentY] } = this.getAbsolutePosition(relativeParent)
+        // eslint-disable-next-line no-use-before-define,no-sequences
+        [pageX, pageY] = [pageX - parentX, pageY - parentY]
+    }
+
+    return {
+      topLeft: [pageX + left, pageY + top],
+      topCenter: [pageX + left + width / 2, pageY + top],
+      topRight: [pageX + left + width, pageY + top],
+      middleLeft: [pageX + left, pageY + top + height / 2],
+      middleCenter: [pageX + left + width / 2, pageY + top + height / 2],
+      middleRight: [pageX + left + width, pageY + top + height / 2],
+      bottomLeft: [pageX + left, pageY + top + height],
+      bottomCenter: [pageX + left + width / 2, pageY + top + height],
+      bottomRight: [pageX + left + width, pageY + top + height]
+    }
+  }
+
+  /**
+   * Setup tooltip attributes
+   * @returns {void}
+   */
+  setupTooltip() {
+    // in case of javascript disabled, the tooltip could use the title attribute as default behaviour
+    // once arrives here, title is no longer necessary
+    this.element.removeAttribute("title")
+
+    this.tooltip.id = this.tooltip.id || `tooltip-${Math.random().toString(36).substring(7)}`
+    // append to dom hidden, to apply css transitions
+    this.tooltip.setAttribute("aria-hidden", true)
+  }
+
+  /**
+   * Calculate and set tooltip position based on its classes
+   * @returns {void}
+   */
+  positionTooltip() {
+    const { topCenter, bottomCenter, middleRight, middleLeft } = this.getAbsolutePosition(this.element)
+
+    let positionX = null
+    let positionY = null
+
+    if (this.tooltip.classList.contains("bottom")) {
+      [positionX, positionY] = bottomCenter
+    } else if (this.tooltip.classList.contains("left")) {
+      [positionX, positionY] = middleLeft
+    } else if (this.tooltip.classList.contains("right")) {
+      [positionX, positionY] = middleRight
+    } else if (this.tooltip.classList.contains("top")) {
+      [positionX, positionY] = topCenter
+    }
+
+    // when the node is placed at the left side of the screen
+    // we translate the tooltip's arrow in order to fit inside the viewport
+    if ((this.tooltip.classList.contains("top") || this.tooltip.classList.contains("bottom")) &&
+      positionX < Math.max(document.documentElement.clientWidth || 0, window.innerWidth || 0) * 0.5) {
+      this.tooltip.style.setProperty("--arrow-offset", "80%")
+    } else {
+      this.tooltip.style.removeProperty("--arrow-offset")
+    }
+
+    this.tooltip.style.top = `${positionY}px`
+    this.tooltip.style.left = `${positionX}px`
+  }
+
+  /**
+   * Show tooltip
+   * @param {Event} event - The click event from the toggle button
+   * @returns {void}
+   */
+  showTooltip(event) {
+    if (event) {
+      event.preventDefault()
+    }
+
+    // remove any previous tooltip from the DOM, in order to avoid overlaps
+    this.removeAllTooltips()
+
+    document.body.appendChild(this.tooltip)
+    this.element.setAttribute("aria-describedby", this.tooltip.id)
+
+    // the position must be calculated once the event has been triggered
+    // in that way, we ensure the container position is that we want
+    // otherwise, the trigger could be hidden or misplaced
+    this.positionTooltip()
+
+    this.tooltip.setAttribute("aria-hidden", false)
+
+    // sleep time before hiding the element from the DOM
+    setTimeout(() => document.addEventListener("click", this.outsideClickHandler))
+  }
+
+  /**
+   * Hide tooltip
+   * @returns {void}
+   */
+  hideTooltip() {
+    if (this.tooltip) {
+      this.tooltip.setAttribute("aria-hidden", "true")
+      document.removeEventListener("click", this.outsideClickHandler)
+    }
+  }
+
+  /**
+   * Toggle tooltip visibility
+   * @param {Event} event - The click event from the toggle button
+   * @returns {void}
+   */
+  toggleTooltip(event) {
+    if (event) {
+      event.preventDefault()
+    }
+
+    // if the tooltip is visible in the DOM, hide it otherwise display
+    if (this.tooltip && this.tooltip.getAttribute("aria-hidden") === "false") {
+      this.hideTooltip()
+      return
+    }
+
+    this.showTooltip(event)
+  }
+
+  /**
+   * Handle outside clicks to close tooltip
+   * @param {Event} event - The click event from outside the button
+   * @returns {void}
+   */
+  handleOutsideClick(event) {
+    if (!this.tooltip.contains(event.target) && event.target !== this.element) {
+      this.hideTooltip()
+    }
+  }
+
+  /**
+   * Handle escape key to close tooltip
+   * @param {Event} event - The keyboard event
+   * @returns {void}
+   */
+  handleEscapeKey(event) {
+    if (event.key === "Escape") {
+      this.hideTooltip()
+    }
+  }
+
+  /**
+   * Remove all existing tooltips from DOM to avoid overlaps
+   * @returns {void}
+   */
+  removeAllTooltips() {
+    Array.from(document.body.children).
+      filter((child) => child.id && child.id.startsWith("tooltip")).
+      forEach((child) => child.remove())
+  }
+
+  /**
+   * Bind appropriate events based on device type
+   * @returns {void}
+   */
+  bindEvents() {
+    if (this.useMobile) {
+      this.bindMobileEvents()
+    } else {
+      this.bindDesktopEvents()
+    }
+  }
+
+  /**
+   * Bind mobile-specific events (click and keyboard)
+   * @returns {void}
+   */
+  bindMobileEvents() {
+    this.element.addEventListener("click", (event) => this.toggleTooltip(event))
+    window.addEventListener("keydown", (event) => this.handleEscapeKey(event))
+  }
+
+  /**
+   * Bind desktop-specific events (hover and focus)
+   * @returns {void}
+   */
+  bindDesktopEvents() {
+    this.element.addEventListener("mouseenter", (event) => this.showTooltip(event))
+    this.element.addEventListener("mouseleave", () => this.hideTooltip())
+    this.element.addEventListener("focus", (event) => this.showTooltip(event))
+    this.element.addEventListener("blur", () => this.hideTooltip())
+
+    // tooltip hover listeners to prevent hiding when hovered
+    if (this.tooltip) {
+      this.tooltip.addEventListener("mouseenter", () => {
+        this.tooltip.setAttribute("aria-hidden", false)
+      })
+      this.tooltip.addEventListener("mouseleave", () => this.hideTooltip())
+    }
+  }
+
+  /**
+   * Clean up when controller disconnects
+   * @returns {void}
+   */
+  cleanup() {
+    if (this.tooltip && this.tooltip.parentNode) {
+      this.tooltip.parentNode.removeChild(this.tooltip)
+    }
+    document.removeEventListener("click", this.outsideClickHandler)
+    window.removeEventListener("keydown", (event) => this.handleEscapeKey(event))
+  }
+
+  /**
+   * Handle tooltip value changes
+   * @returns {void}
+   */
+  tooltipValueChanged() {
+    if (this.tooltip) {
+      this.cleanup()
+    }
+    this.initialize()
+  }
+}