srcdev-nuxt-components 9.5.5 → 9.5.6

package/app/composables/tests/useAnchoredPopover.spec.ts

@@ -0,0 +1,231 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import { defineComponent, h, nextTick, ref } from "vue";
+import { useAnchoredPopover, type AnchoredPopoverSide } from "../useAnchoredPopover";
+
+type Support = { popover: boolean; anchor: boolean };
+
+const setSupport = ({ popover, anchor }: Support) => {
+  Object.defineProperty(HTMLElement.prototype, "showPopover", {
+    value: popover ? vi.fn() : undefined,
+    writable: true,
+    configurable: true,
+  });
+  Object.defineProperty(HTMLElement.prototype, "hidePopover", {
+    value: popover ? vi.fn() : undefined,
+    writable: true,
+    configurable: true,
+  });
+  // happy-dom's CSS.supports can't be spied on, so swap the whole global and restore it in afterEach.
+  Object.defineProperty(globalThis, "CSS", { value: { supports: () => anchor }, writable: true, configurable: true });
+};
+
+const originalCSS = globalThis.CSS;
+
+const setViewport = (width: number, height: number) => {
+  Object.defineProperty(document.documentElement, "clientWidth", { value: width, configurable: true });
+  Object.defineProperty(document.documentElement, "clientHeight", { value: height, configurable: true });
+};
+
+const mountHost = (side: AnchoredPopoverSide = "bottom") => {
+  const onOpen = vi.fn();
+  const mounted = mountSuspended(
+    defineComponent({
+      setup() {
+        const rootRef = ref<HTMLElement | null>(null);
+        const triggerRef = ref<HTMLElement | null>(null);
+        const popoverRef = ref<HTMLElement | null>(null);
+        return { rootRef, triggerRef, popoverRef, ...useAnchoredPopover({ rootRef, triggerRef, popoverRef, side, onOpen }) };
+      },
+      render() {
+        return h("div", [
+          h("div", { ref: "rootRef", class: "root" }, [
+            h("button", { ref: "triggerRef", class: "trigger", onClick: this.handleTriggerClick }),
+            h("div", { ref: "popoverRef", class: "popover" }),
+          ]),
+          h("button", { class: "outside" }),
+        ]);
+      },
+    }),
+    { attachTo: document.body }
+  );
+  return { mounted, onOpen };
+};
+
+const mockTriggerRect = (wrapper: Awaited<ReturnType<typeof mountHost>["mounted"]>, rect: Partial<DOMRect>) => {
+  const trigger = wrapper.find(".trigger").element as HTMLElement;
+  vi.spyOn(trigger, "getBoundingClientRect").mockReturnValue({ top: 0, bottom: 0, left: 0, right: 0, ...rect } as DOMRect);
+};
+
+const mockPopoverSize = (wrapper: Awaited<ReturnType<typeof mountHost>["mounted"]>, width: number, height: number) => {
+  const popover = wrapper.find(".popover").element;
+  Object.defineProperty(popover, "offsetWidth", { value: width, configurable: true });
+  Object.defineProperty(popover, "offsetHeight", { value: height, configurable: true });
+};
+
+describe("useAnchoredPopover", () => {
+  beforeEach(() => {
+    setViewport(1000, 800);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    delete (HTMLElement.prototype as unknown as Record<string, unknown>)["showPopover"];
+    delete (HTMLElement.prototype as unknown as Record<string, unknown>)["hidePopover"];
+    delete (document.documentElement as unknown as Record<string, unknown>)["clientWidth"];
+    delete (document.documentElement as unknown as Record<string, unknown>)["clientHeight"];
+    Object.defineProperty(globalThis, "CSS", { value: originalCSS, writable: true, configurable: true });
+    document.body.innerHTML = "";
+  });
+
+  describe("native Popover API and anchor positioning", () => {
+    beforeEach(() => setSupport({ popover: true, anchor: true }));
+
+    it("uses neither fallback", async () => {
+      const wrapper = await mountHost().mounted;
+      expect(wrapper.vm.usesFallbackPopover).toBe(false);
+      expect(wrapper.vm.needsPositioning).toBe(false);
+      expect(wrapper.vm.positionStyle).toBeUndefined();
+      expect(wrapper.vm.popoverPlacement).toBeUndefined();
+    });
+
+    it("show and hide call the native methods", async () => {
+      const wrapper = await mountHost().mounted;
+      const popover = wrapper.find(".popover").element as HTMLElement;
+      wrapper.vm.show();
+      wrapper.vm.hide();
+      expect(popover.showPopover).toHaveBeenCalledOnce();
+      expect(popover.hidePopover).toHaveBeenCalledOnce();
+    });
+
+    it("trigger click is left to popovertarget", async () => {
+      const wrapper = await mountHost().mounted;
+      await wrapper.find(".trigger").trigger("click");
+      expect(wrapper.vm.isOpen).toBe(false);
+    });
+
+    it("tracks isOpen and calls onOpen from the toggle event", async () => {
+      const { mounted, onOpen } = mountHost();
+      const wrapper = await mounted;
+      wrapper.vm.handleToggle(Object.assign(new Event("toggle"), { newState: "open" }));
+      expect(wrapper.vm.isOpen).toBe(true);
+      expect(onOpen).toHaveBeenCalledOnce();
+
+      wrapper.vm.handleToggle(Object.assign(new Event("toggle"), { newState: "closed" }));
+      expect(wrapper.vm.isOpen).toBe(false);
+    });
+  });
+
+  describe("without the Popover API", () => {
+    beforeEach(() => setSupport({ popover: false, anchor: true }));
+
+    it("detects the fallback on mount", async () => {
+      const wrapper = await mountHost().mounted;
+      expect(wrapper.vm.usesFallbackPopover).toBe(true);
+    });
+
+    it("toggles open and closed from the trigger, calling onOpen after render", async () => {
+      const { mounted, onOpen } = mountHost();
+      const wrapper = await mounted;
+
+      await wrapper.find(".trigger").trigger("click");
+      expect(wrapper.vm.isOpen).toBe(true);
+      await nextTick();
+      expect(onOpen).toHaveBeenCalledOnce();
+
+      await wrapper.find(".trigger").trigger("click");
+      expect(wrapper.vm.isOpen).toBe(false);
+    });
+
+    it("closes on a pointerdown outside the root, not inside it", async () => {
+      const wrapper = await mountHost().mounted;
+      wrapper.vm.show();
+      await nextTick();
+
+      wrapper.find(".popover").element.dispatchEvent(new Event("pointerdown", { bubbles: true }));
+      expect(wrapper.vm.isOpen).toBe(true);
+
+      wrapper.find(".outside").element.dispatchEvent(new Event("pointerdown", { bubbles: true }));
+      expect(wrapper.vm.isOpen).toBe(false);
+    });
+
+    it("closes on Escape and returns focus to the trigger", async () => {
+      const wrapper = await mountHost().mounted;
+      const focusSpy = vi.spyOn(wrapper.find(".trigger").element as HTMLElement, "focus");
+      wrapper.vm.show();
+      await nextTick();
+
+      document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));
+      expect(wrapper.vm.isOpen).toBe(false);
+      expect(focusSpy).toHaveBeenCalledOnce();
+    });
+
+    it("stops listening once closed", async () => {
+      const wrapper = await mountHost().mounted;
+      const focusSpy = vi.spyOn(wrapper.find(".trigger").element as HTMLElement, "focus");
+      wrapper.vm.show();
+      await nextTick();
+      wrapper.vm.hide();
+
+      document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));
+      expect(focusSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("without anchor positioning", () => {
+    beforeEach(() => setSupport({ popover: true, anchor: false }));
+
+    const openWith = async (side: AnchoredPopoverSide, rect: Partial<DOMRect>, size = { width: 100, height: 200 }) => {
+      const wrapper = await mountHost(side).mounted;
+      mockTriggerRect(wrapper, rect);
+      mockPopoverSize(wrapper, size.width, size.height);
+      wrapper.vm.handleToggle(Object.assign(new Event("toggle"), { newState: "open" }));
+      return wrapper;
+    };
+
+    it("writes every trigger edge, plain and measured from the viewport's far edge", async () => {
+      const wrapper = await mountHost().mounted;
+      mockTriggerRect(wrapper, { top: 100, bottom: 140, left: 50, right: 250 });
+
+      wrapper.vm.handleBeforeToggle(Object.assign(new Event("beforetoggle"), { newState: "open" }));
+      expect(wrapper.vm.needsPositioning).toBe(true);
+      expect(wrapper.vm.positionStyle).toEqual({
+        "--_anchor-top": "100px",
+        "--_anchor-bottom": "140px",
+        "--_anchor-left": "50px",
+        "--_anchor-right": "250px",
+        "--_anchor-top-inverse": "700px",
+        "--_anchor-bottom-inverse": "660px",
+        "--_anchor-left-inverse": "950px",
+        "--_anchor-right-inverse": "750px",
+      });
+    });
+
+    it("ignores beforetoggle when closing", async () => {
+      const wrapper = await mountHost().mounted;
+      mockTriggerRect(wrapper, { top: 100, bottom: 140, left: 50, right: 250 });
+
+      wrapper.vm.handleBeforeToggle(Object.assign(new Event("beforetoggle"), { newState: "closed" }));
+      expect(wrapper.vm.positionStyle).toMatchObject({ "--_anchor-top": "0px" });
+    });
+
+    it.each([
+      ["bottom", { top: 100, bottom: 140, left: 400, right: 450 }, "bottom"],
+      ["bottom", { top: 700, bottom: 740, left: 400, right: 450 }, "top"],
+      ["top", { top: 300, bottom: 340, left: 400, right: 450 }, "top"],
+      ["top", { top: 100, bottom: 140, left: 400, right: 450 }, "bottom"],
+      ["right", { top: 300, bottom: 340, left: 400, right: 450 }, "right"],
+      ["right", { top: 300, bottom: 340, left: 850, right: 950 }, "left"],
+      ["left", { top: 300, bottom: 340, left: 400, right: 450 }, "left"],
+      ["left", { top: 300, bottom: 340, left: 50, right: 100 }, "right"],
+    ] as const)("prefers %s and resolves to %s for %o", async (side, rect, expected) => {
+      const wrapper = await openWith(side, rect);
+      expect(wrapper.vm.popoverPlacement).toBe(expected);
+    });
+
+    it("keeps the preferred side when neither side has room", async () => {
+      const wrapper = await openWith("bottom", { top: 100, bottom: 140, left: 50, right: 250 }, { width: 100, height: 900 });
+      expect(wrapper.vm.popoverPlacement).toBe("bottom");
+    });
+  });
+});

package/app/composables/tests/useTooltips.spec.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import { defineComponent, h, nextTick, ref } from "vue";
+import { useTooltipsGuide } from "../useTooltips";
+import DisplayTooltipDefined from "~/components/02.molecules/display-tooltip-defined/DisplayTooltipDefined.vue";
+
+const flush = async () => {
+  for (let i = 0; i < 5; i++) await nextTick();
+};
+
+const mountGuide = () =>
+  mountSuspended(
+    defineComponent({
+      setup() {
+        const containerRef = ref<HTMLElement | null>(null);
+        const guide = useTooltipsGuide(containerRef, { autoStart: false, startDelay: 0 });
+        return { containerRef, guide };
+      },
+      render() {
+        return h("div", { ref: "containerRef" }, [
+          h(DisplayTooltipDefined, { tooltipId: "one", contentText: { tooltipTitle: { tag: "h4", text: "One" } } }),
+          h(DisplayTooltipDefined, { tooltipId: "two", contentText: { tooltipTitle: { tag: "h4", text: "Two" } } }),
+        ]);
+      },
+    }),
+    { attachTo: document.body }
+  );
+
+describe("useTooltipsGuide without the Popover API", () => {
+  beforeEach(() => {
+    Object.defineProperty(HTMLElement.prototype, "showPopover", { value: undefined, writable: true, configurable: true });
+  });
+
+  afterEach(() => {
+    delete (HTMLElement.prototype as unknown as Record<string, unknown>)["showPopover"];
+    document.body.innerHTML = "";
+  });
+
+  it("steps through each tooltip as its close button is clicked", async () => {
+    const wrapper = await mountGuide();
+    const vm = wrapper.vm as unknown as { guide: ReturnType<typeof useTooltipsGuide> };
+    const popovers = () => wrapper.findAll(".display-tooltip-popover");
+
+    vm.guide.initializePopovers();
+    void vm.guide.startGuide();
+    await flush();
+    expect(popovers()[0]!.classes()).toContain("display-tooltip-popover-open");
+
+    await wrapper.findAll(".display-tooltip-close-button")[0]!.trigger("click");
+    await flush();
+    expect(popovers()[0]!.classes()).not.toContain("display-tooltip-popover-open");
+    expect(popovers()[1]!.classes()).toContain("display-tooltip-popover-open");
+    expect(vm.guide.currentTooltipIndex.value).toBe(1);
+  });
+
+  it("stopGuide closes the open tooltip without calling Popover API methods", async () => {
+    const wrapper = await mountGuide();
+    const vm = wrapper.vm as unknown as { guide: ReturnType<typeof useTooltipsGuide> };
+
+    vm.guide.initializePopovers();
+    void vm.guide.startGuide();
+    await flush();
+
+    expect(() => vm.guide.stopGuide()).not.toThrow();
+    await flush();
+    expect(wrapper.find(".display-tooltip-popover-open").exists()).toBe(false);
+    expect(vm.guide.isGuideRunning.value).toBe(false);
+  });
+});

package/app/composables/useAnchoredPopover.ts

@@ -0,0 +1,183 @@
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+interface AnchoredPopoverOptions {
+  rootRef: Readonly<Ref<HTMLElement | null>>;
+  triggerRef: Readonly<Ref<HTMLElement | null>>;
+  popoverRef: Readonly<Ref<HTMLElement | null>>;
+  side?: MaybeRefOrGetter<AnchoredPopoverSide>;
+  onOpen?: () => void;
+}
+
+export type AnchoredPopoverSide = "top" | "right" | "bottom" | "left";
+
+type PopoverToggleEvent = Event & { newState?: string };
+
+const OPPOSITE_SIDE: Record<AnchoredPopoverSide, AnchoredPopoverSide> = {
+  top: "bottom",
+  bottom: "top",
+  left: "right",
+  right: "left",
+};
+
+// Native popover + anchor positioning where supported; JS positioning without anchor positioning
+// (Safari 17-18); JS open/close, outside click and Escape without the Popover API (Safari 16).
+export function useAnchoredPopover({ rootRef, triggerRef, popoverRef, side = "bottom", onOpen }: AnchoredPopoverOptions) {
+  const isOpen = ref(false);
+  const usesFallbackPopover = ref(false);
+  const needsPositioning = ref(false);
+  const placement = ref<AnchoredPopoverSide>(toValue(side));
+  const anchor = ref({ top: 0, bottom: 0, left: 0, right: 0, viewportWidth: 0, viewportHeight: 0 });
+
+  // `--_anchor-{edge}` mirrors anchor({edge}) for top/left; `-inverse` is the same edge measured
+  // from the viewport's bottom/right, for bottom/right.
+  const positionStyle = computed(() => {
+    if (!needsPositioning.value) return undefined;
+    const { top, bottom, left, right, viewportWidth, viewportHeight } = anchor.value;
+    return {
+      "--_anchor-top": `${top}px`,
+      "--_anchor-bottom": `${bottom}px`,
+      "--_anchor-left": `${left}px`,
+      "--_anchor-right": `${right}px`,
+      "--_anchor-top-inverse": `${viewportHeight - top}px`,
+      "--_anchor-bottom-inverse": `${viewportHeight - bottom}px`,
+      "--_anchor-left-inverse": `${viewportWidth - left}px`,
+      "--_anchor-right-inverse": `${viewportWidth - right}px`,
+    };
+  });
+
+  const popoverPlacement = computed(() => (needsPositioning.value ? placement.value : undefined));
+
+  const updatePosition = () => {
+    const trigger = triggerRef.value;
+    if (!trigger) return;
+    const rect = trigger.getBoundingClientRect();
+    const viewportWidth = document.documentElement.clientWidth;
+    const viewportHeight = document.documentElement.clientHeight;
+    const width = popoverRef.value?.offsetWidth ?? 0;
+    const height = popoverRef.value?.offsetHeight ?? 0;
+
+    const fits: Record<AnchoredPopoverSide, boolean> = {
+      bottom: rect.bottom + height <= viewportHeight,
+      top: rect.top - height >= 0,
+      right: rect.right + width <= viewportWidth,
+      left: rect.left - width >= 0,
+    };
+
+    anchor.value = { top: rect.top, bottom: rect.bottom, left: rect.left, right: rect.right, viewportWidth, viewportHeight };
+    const preferred = toValue(side);
+    placement.value = fits[preferred] || !fits[OPPOSITE_SIDE[preferred]] ? preferred : OPPOSITE_SIDE[preferred];
+  };
+
+  let frame = 0;
+  const schedulePositionUpdate = () => {
+    if (frame) return;
+    frame = requestAnimationFrame(() => {
+      frame = 0;
+      updatePosition();
+    });
+  };
+
+  const handleDocumentPointerdown = (event: PointerEvent) => {
+    if (!rootRef.value?.contains(event.target as Node)) hide();
+  };
+
+  const handleDocumentKeydown = (event: KeyboardEvent) => {
+    if (event.key !== "Escape") return;
+    hide();
+    triggerRef.value?.focus();
+  };
+
+  const addListeners = () => {
+    if (needsPositioning.value) {
+      window.addEventListener("scroll", schedulePositionUpdate, { capture: true, passive: true });
+      window.addEventListener("resize", schedulePositionUpdate, { passive: true });
+    }
+    if (usesFallbackPopover.value) {
+      document.addEventListener("pointerdown", handleDocumentPointerdown);
+      document.addEventListener("keydown", handleDocumentKeydown);
+    }
+  };
+
+  const removeListeners = () => {
+    window.removeEventListener("scroll", schedulePositionUpdate, { capture: true });
+    window.removeEventListener("resize", schedulePositionUpdate);
+    document.removeEventListener("pointerdown", handleDocumentPointerdown);
+    document.removeEventListener("keydown", handleDocumentKeydown);
+    if (frame) cancelAnimationFrame(frame);
+    frame = 0;
+  };
+
+  const afterOpen = () => {
+    if (needsPositioning.value) updatePosition();
+    addListeners();
+  };
+
+  const show = () => {
+    if (!usesFallbackPopover.value) {
+      popoverRef.value?.showPopover();
+      return;
+    }
+    if (isOpen.value) return;
+    if (needsPositioning.value) updatePosition();
+    isOpen.value = true;
+    nextTick(() => {
+      afterOpen();
+      onOpen?.();
+    });
+  };
+
+  const hide = () => {
+    if (!usesFallbackPopover.value) {
+      popoverRef.value?.hidePopover();
+      return;
+    }
+    if (!isOpen.value) return;
+    // Matches native popovers, which return focus to the invoker when focus was inside.
+    if (popoverRef.value?.contains(document.activeElement)) triggerRef.value?.focus();
+    isOpen.value = false;
+    removeListeners();
+  };
+
+  /** Bound to the trigger's click. A no-op where `popovertarget` already toggles natively. */
+  const handleTriggerClick = () => {
+    if (!usesFallbackPopover.value) return;
+    if (isOpen.value) hide();
+    else show();
+  };
+
+  /** Bound to the popover's `beforetoggle`, so the first open frame is already in place. */
+  const handleBeforeToggle = (event: Event) => {
+    if (needsPositioning.value && (event as PopoverToggleEvent).newState === "open") updatePosition();
+  };
+
+  /** Bound to the popover's `toggle`. */
+  const handleToggle = (event: Event) => {
+    isOpen.value = (event as PopoverToggleEvent).newState === "open";
+    if (isOpen.value) {
+      afterOpen();
+      onOpen?.();
+    } else {
+      removeListeners();
+    }
+  };
+
+  onMounted(() => {
+    usesFallbackPopover.value = typeof HTMLElement.prototype.showPopover !== "function";
+    needsPositioning.value = typeof CSS !== "undefined" && typeof CSS.supports === "function" && !CSS.supports("anchor-name: --a");
+  });
+
+  onBeforeUnmount(removeListeners);
+
+  return {
+    isOpen,
+    usesFallbackPopover,
+    needsPositioning,
+    positionStyle,
+    popoverPlacement,
+    show,
+    hide,
+    handleTriggerClick,
+    handleBeforeToggle,
+    handleToggle,
+  };
+}

package/app/composables/useTooltips.ts

@@ -32,23 +32,40 @@ export const useTooltipsGuide = (
     })
   }
 
+  const findTrigger = (popover: HTMLElement) =>
+    document.querySelector<HTMLElement>(`[popovertarget="${popover.id}"][popovertargetaction="toggle"]`)
+
+  // Without the Popover API (Safari 16) there's no togglePopover() and :popover-open throws, so
+  // tooltips are driven through their trigger, whose aria-expanded tracks the open state everywhere.
+  const closePopover = (popover: HTMLElement) => {
+    const trigger = findTrigger(popover)
+    if (trigger?.getAttribute("aria-expanded") === "true") {
+      trigger.click()
+      return
+    }
+    if (typeof popover.hidePopover !== "function") return
+    try {
+      if (popover.matches(":popover-open")) popover.hidePopover()
+    } catch {
+      // :popover-open unsupported
+    }
+  }
+
   /**
    * Show a tooltip and wait for user dismissal
    */
   const showTooltipAndWaitForDismiss = (popover: HTMLElement): Promise<void> => {
     return new Promise((resolve) => {
-      // Find the trigger button that corresponds to this popover
-      const popoverId = popover.id
-      const triggerButton = document.querySelector<HTMLElement>(
-        `[popovertarget="${popoverId}"][popovertargetaction="toggle"]`
-      )
+      const triggerButton = findTrigger(popover)
 
       // Use the trigger button to show the popover to maintain proper anchor relationship
       if (triggerButton) {
         triggerButton.click()
-      } else {
-        // Fallback if no trigger button found
+      } else if (typeof popover.togglePopover === "function") {
         popover.togglePopover(true)
+      } else {
+        resolve()
+        return
       }
 
       // Find the close button within this popover
@@ -62,10 +79,18 @@ export const useTooltipsGuide = (
         }
 
         closeButton.addEventListener("click", handleClose)
+      } else if (triggerButton) {
+        // No close button: resolve once the trigger reports the tooltip closed
+        const observer = new MutationObserver(() => {
+          if (triggerButton.getAttribute("aria-expanded") === "false") {
+            observer.disconnect()
+            resolve()
+          }
+        })
+        observer.observe(triggerButton, { attributes: true, attributeFilter: ["aria-expanded"] })
       } else {
-        // Fallback: listen for the popover to be hidden
-        const handleToggle = () => {
-          if (!popover.matches(":popover-open")) {
+        const handleToggle = (event: Event) => {
+          if ((event as Event & { newState?: string }).newState === "closed") {
             popover.removeEventListener("toggle", handleToggle)
             resolve()
           }
@@ -105,11 +130,7 @@ export const useTooltipsGuide = (
     if (isGuideRunning.value) return
 
     // Close any currently open popovers
-    popovers.forEach((popover) => {
-      if (popover.matches(":popover-open")) {
-        popover.togglePopover(false)
-      }
-    })
+    popovers.forEach(closePopover)
 
     // Reset state and start the guide
     autoRunGuide.value = true
@@ -123,11 +144,7 @@ export const useTooltipsGuide = (
     if (!isGuideRunning.value) return
 
     // Close any currently open popovers
-    popovers.forEach((popover) => {
-      if (popover.matches(":popover-open")) {
-        popover.togglePopover(false)
-      }
-    })
+    popovers.forEach(closePopover)
 
     isGuideRunning.value = false
     autoRunGuide.value = false

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "srcdev-nuxt-components",
   "type": "module",
-  "version": "9.5.5",
+  "version": "9.5.6",
   "main": "nuxt.config.ts",
   "types": "types.d.ts",
   "license": "MIT",