@tilli-pro/cookieconsent-plugin 0.1.0

package/src/config/gui-options/html-components/ManageCookiePrefsButton.ts

@@ -0,0 +1,121 @@
+"use client";
+
+import CookieIcon from "./assets/CookieIcon";
+
+const translations = {
+  en: {
+    manageCookiePreferences: "Manage cookie preferences",
+  },
+};
+
+export const buttonId = "tilli-manage-cookie-preferences-floating-button";
+export const containerId = `${buttonId}-container`;
+
+/**
+ * returns HTML for a floating "manage cookie preferences" button.
+ *
+ *  > by default, the button is visible -- however, if `#cc-main` (which
+ *    appears *earlier* in the DOM and is thus a preceding sibling to
+ *    `#${containerId}`) is still visible (i.e., the cookie consent modal),
+ *    the entire container (`#${containerId}`) will be hidden.
+ */
+export default (lang: keyof typeof translations = "en"): string => `
+<!-- floating cookie consent "manage preferences" icon button -->
+<abbr title="${translations[lang].manageCookiePreferences}">
+  <button
+    id="${buttonId}"
+    type="button"
+    data-cc="${
+      /**
+       * auto-add "onClick" functionality -- @see https://cookieconsent.orestbida.com/essential/getting-started.html#how-to-open-the-preferences-modal
+       *
+       * @deprecated (can stay, no harm) prefer `CookieConsent.showPreferences()` since `data-cc="show-preferencesModal"` will only work if this cookie prefs button is injected PRIOR to running `CookieConsent.run()` -- @see https://cookieconsent.orestbida.com/reference/api-reference.html#showpreferences
+       */
+      "show-preferencesModal"
+    }"
+    aria-label="${translations[lang].manageCookiePreferences}"
+  >
+    <style>
+      #${buttonId} {
+        /* floats @ the bottom right */
+        position: fixed;
+        bottom: 1rem;
+        right: 1rem;
+        z-index: 9999999;
+
+        /* sizing + layout */
+        width: 2rem;
+        height: 2rem;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+
+        /* circular button background -- NOTE(IMPORTANT): must adhere to contrast guidelines -- @see https://webaim.org/resources/contrastchecker */
+        background-color: #fff;
+        border: 1px solid #ddd;
+        border-radius: 50%;
+        padding: 0.25rem;              /* "fat-finger"-friendly padding */
+        box-shadow: 0 4px 6px rgba(0,0,0,0.1);
+        cursor: pointer;
+
+        /* transitions for hover/focus states */
+        transition: box-shadow 0.2s ease;
+        animation: fadeIn var(--cc-modal-transition-duration) ease-in-out forwards;
+
+        /* ensure always-interactable + visible */
+        pointer-events: auto;
+        visibility: visible !important;
+      }
+
+      .dark #${buttonId} {
+        background-color: #000;
+        border-color: #333;
+      }
+
+      #${buttonId}:hover,
+      #${buttonId}:focus {
+        box-shadow: 0 4px 12px rgba(0,0,0,0.2);
+      }
+
+      #${buttonId}:focus-visible {
+        outline: none;                 /* remove default blue outline */
+      }
+
+      /* the icon itself (SVG), scaled: */
+      #${buttonId} svg {
+        width: 1.5rem;
+        height: 1.5rem;
+        display: block;
+      }
+
+      @keyframes fadeIn {
+        0% {
+          opacity: 0;
+          transform: translateY(50%);
+        }
+        100% {
+          opacity: 1;
+          transform: translateY(0);
+        }
+      }
+
+      /* default: display the container so the button is visible */
+      #${containerId} {
+        display: block;
+      }
+
+      /* 
+        hide the entire container IF AND ONLY IF:
+        - #cc-main (earlier sibling) has .cm-wrapper
+        - That .cm-wrapper has a .cm
+        - That .cm has [aria-hidden="false"] (i.e., the cookie consent modal is visible)
+      */
+      #cc-main:has(.cm-wrapper .cm[aria-hidden="false"]) ~ #${containerId} {
+        display: none !important;
+      }
+    </style>
+
+    ${CookieIcon(1)}
+  </button>
+</abbr>
+`;

package/src/config/gui-options/html-components/TilliXCallout.ts

@@ -0,0 +1,34 @@
+"use client";
+
+import assets from "../../../assets";
+
+const translations = {
+  de: {
+    poweredByTilliX: "unterstützt von tilliX",
+  },
+  en: {
+    poweredByTilliX: "powered by tilliX",
+  },
+  es: {
+    poweredByTilliX: "impulsado por tilliX",
+  },
+  fr: {
+    poweredByTilliX: "propulsé par tilliX",
+  },
+  it: {
+    poweredByTilliX: "alimentato da tilliX",
+  },
+};
+
+export default (
+  lang: keyof typeof translations = "en",
+  inPrefs?: boolean | (1 | 0), // 😉
+): string => `
+<!-- "powered by tilliX" callout -->
+<div style="${!inPrefs ? "margin-left: auto; " : ""}margin-top: auto; margin-bottom: auto">
+  <abbr title="${translations[lang].poweredByTilliX}" style="${inPrefs ? "margin-right: 1em" : "margin-left: 1.3rem"}; display: flex; align-items: center">
+    <a href="https://tilli.pro" target="_blank" style="display: inline-block; background-image: none">
+      <img src="data:image/svg+xml;charset=utf8,${encodeURIComponent(assets.logo)}" alt="tilli" style="height: 1em; width: auto; min-height: 1em; min-width: 1em; vertical-align: middle" />
+    </a>
+  </abbr>
+</div>`;

package/src/config/gui-options/html-components/assets/CookieIcon.ts

@@ -0,0 +1,15 @@
+"use client";
+
+import assets from "../../../../assets";
+
+export default (
+  centered?: boolean | (1 | 0) /* 😉 */,
+  scale = 0.6667, // -> 0.6667 ((100 * n)%)
+  topOffset = 0, // -> -0.25 (em)
+  rightOffset = 0, // -> 0.25 (em)
+): string => `
+<span style="display: inline-block; vertical-align: middle; transform: scale(${scale}); transform-origin: top left; margin-right: ${((centered ? -0.5 : -0.25) + rightOffset).toFixed(4)}em; height: 1em${topOffset ? `; margin-top: ${topOffset.toFixed(4)}em` : ""};">
+  ${assets.cookie}
+  <!-- invisible "🍪" icon (used for copy-paste/a11y purposes) -->
+  <span style="max-width: 0; max-height: 0; opacity: 0; position: absolute">🍪</span>
+</span>`;

package/src/config/gui-options/index.ts

@@ -0,0 +1,19 @@
+import type { GuiOptions } from "@tilli-pro/cookieconsent";
+
+/** IMPORTANT NOTES FOR GDPR COMPLIANCE:
+ * > the "Accept" and "Reject" buttons should be equally weighted in terms of size, color, and font. This means that the buttons should be equally accessible and prominent– `equalWeightButtons` must be `true`. */
+
+export default {
+  consentModal: {
+    layout: "box",
+    position: "bottom left",
+    equalWeightButtons: true, // IMPORTANT: MUST BE `true` TO BE GDPR-COMPLIANT
+    flipButtons: false,
+  },
+  preferencesModal: {
+    layout: "box",
+    position: "right", // not in use since we use "box" (aka a modal)– if we use "bar" (aka a drawer), this will be used
+    equalWeightButtons: true, // IMPORTANT: MUST BE `true` TO BE GDPR-COMPLIANT
+    flipButtons: false,
+  },
+} satisfies GuiOptions;

package/src/config/gui-options/scripts/cookiePrefsButtonDragObserver.ts

@@ -0,0 +1,180 @@
+"use client";
+
+import { showPreferences } from "@tilli-pro/cookieconsent";
+
+import { buttonId } from "../html-components/ManageCookiePrefsButton";
+
+/**
+ * attach a MutationObserver the **first time** the user hovers over–
+ * enabling a limited "drag up" functionality for the floating button.
+ *  > this is a purposeful UX enhancement to allow users to move the button
+ *    out of the way in case it’s blocking content/functionality underneath.
+ *
+ * @usage simply attach this function to the `onmouseover` event of the floating button.
+ * @see {@link ./injectManageCookiePrefsButton.tsx HTMLDivElement["onmouseover"]} for the full implementation.
+ */
+export default (function <IsTouch extends boolean = false>(
+  this: HTMLDivElement,
+  e: MouseEvent,
+) {
+  /** we store a data-attribute (`hasTilliCookiePrefsDragObserverInit`) to avoid reattaching
+   * the logic on multiple hovers -- this ensures the script is only initiated once. */
+  if (this.dataset.hasTilliCookiePrefsDragObserverInit === "true") return;
+  this.dataset.hasTilliCookiePrefsDragObserverInit = "true";
+
+  let isDragging = false;
+  let startY = 0;
+  let initialBottomPx = 0;
+  let hasListeners = false; // track whether we've attached the events yet
+
+  /** we'll dynamically calculate these values on the first drag */
+  let lowestBottomPx = 0;
+  let highestBottomPx = 0;
+
+  // DRAG LOGIC
+  function onMouseDown(this: HTMLElement, e: MouseEvent) {
+    if (e.button !== 0) return; // only drag on left-click
+    e.preventDefault();
+
+    isDragging = true;
+    startY = e.clientY;
+
+    /** on each new drag, read the button’s *current* bottom */
+    const buttonStyle = window.getComputedStyle(this);
+    initialBottomPx = parseFloat(buttonStyle.bottom) || 16;
+  }
+
+  function onMouseMove(this: HTMLElement, e: MouseEvent) {
+    if (!isDragging) return;
+
+    /** positive delta => pointer moving down => button goes up */
+    const dragDelta = startY - e.clientY;
+    let newBottomPx = initialBottomPx + dragDelta;
+
+    /** clamp between lowestBottomPx and highestBottomPx */
+    if (newBottomPx < lowestBottomPx) newBottomPx = lowestBottomPx;
+    if (newBottomPx > highestBottomPx) newBottomPx = highestBottomPx;
+
+    this.style.bottom = `${newBottomPx}px`;
+  }
+
+  function onMouseUp() {
+    isDragging = false;
+  }
+
+  // [mobile (touch) support]
+  // - we also want to allow dragging on touch devices
+  // - we're using the same logic as mouse dragging, but with touch events
+  function onTouchStart(this: HTMLElement, e: TouchEvent) {
+    if (e.touches?.length !== 1) return; // only drag with one finger
+    e.preventDefault();
+    isDragging = true;
+    startY = e.touches[0]?.clientY ?? startY;
+
+    const buttonStyle = window.getComputedStyle(this);
+    initialBottomPx = parseFloat(buttonStyle.bottom) || 16;
+  }
+
+  function onTouchMove(this: HTMLElement, e: TouchEvent) {
+    if (!isDragging) return;
+
+    if (!e.touches?.[0]) return;
+    const dragDelta = startY - e.touches[0].clientY;
+    let newBottomPx = initialBottomPx + dragDelta;
+
+    if (newBottomPx < lowestBottomPx) newBottomPx = lowestBottomPx;
+    if (newBottomPx > highestBottomPx) newBottomPx = highestBottomPx;
+
+    this.style.bottom = `${newBottomPx}px`;
+  }
+
+  function onTouchEnd() {
+    isDragging = false;
+  }
+
+  function attachDragEvents(buttonEl: HTMLElement) {
+    if (hasListeners) return; // only attach once
+    hasListeners = true;
+
+    /** determine max drag distance (based on button height) */
+    const buttonStyle = window.getComputedStyle(buttonEl);
+    const originalBottomPx = parseFloat(buttonStyle.bottom) || 16; // fallback to ~1rem
+    const buttonHeightPx = parseFloat(buttonStyle.height) || 32; // fallback to ~2rem
+    const maxDragPx = buttonHeightPx * 1.1; // added 10% extra to be safe
+
+    /** the user can drag from the original position (lowestBottomPx) up by that computed distance (highestBottomPx). */
+    lowestBottomPx = originalBottomPx;
+    highestBottomPx = originalBottomPx + maxDragPx;
+
+    /** attach the mouse events for dragging */
+    buttonEl.addEventListener("mousedown", onMouseDown.bind(buttonEl));
+    document.addEventListener("mousemove", onMouseMove.bind(buttonEl));
+    document.addEventListener("mouseup", onMouseUp);
+    // [mobile (touch) support]
+    buttonEl.addEventListener("touchstart", onTouchStart.bind(buttonEl));
+    document.addEventListener("touchmove", onTouchMove.bind(buttonEl));
+    document.addEventListener("touchend", onTouchEnd);
+  }
+
+  // MUTATION OBSERVER – for if the button is removed/re-added
+  const observer = new MutationObserver(() => {
+    const button = document.getElementById(buttonId);
+    if (!button) {
+      hasListeners = false; // if button was removed, reset flags
+      isDragging = false;
+      return;
+    }
+    attachDragEvents(button);
+  });
+  observer.observe(document.body, { childList: true, subtree: true });
+
+  /** if the button is already present, attach drag events immediately */
+  const button = document.getElementById(buttonId);
+  if (button) attachDragEvents(button);
+} as <IsTouch extends boolean = false>() => HTMLDivElement[IsTouch extends true
+  ? "ontouchstart"
+  : "onmouseover"]);
+
+export type HTMLDivElementWithDragObserver = HTMLDivElement & {
+  _startX?: number | null;
+  _startY?: number | null;
+};
+
+/** determine whether the user "tapped" or "dragged" (open prefs if "tapped") */
+export const ontouchend = function ontouchend(
+  this: HTMLDivElementWithDragObserver,
+  e: TouchEvent,
+): void {
+  const touch = e.changedTouches[0];
+  const { clientX: endX, clientY: endY } = touch ?? {};
+  if (!endX || !endY) return;
+
+  /** retrieve stored start coordinates */
+  const startX = this._startX ?? endX;
+  const startY = this._startY ?? endY;
+
+  /** threshold for "same spot" */
+  const threshold = 10; // maximum allowable movement (in pixels)
+
+  /** make sure the user ended their touch in *relatively* the "same spot" as they started */
+  if (
+    Math.abs(endX - startX) <= threshold &&
+    Math.abs(endY - startY) <= threshold
+  )
+    /** user ended the touch near where it started, open preferences */
+    showPreferences(); /** prefer over `data-cc="show-preferencesModal"` -- @see https://cookieconsent.orestbida.com/reference/api-reference.html#showpreferences */
+
+  /** reset coordinates to avoid future issues */
+  this._startX = null;
+  this._startY = null;
+} as HTMLDivElementWithDragObserver["ontouchend"];
+
+/** store the touch start coordinates */
+export const ontouchstart = function ontouchstart(
+  this: HTMLDivElementWithDragObserver,
+  e: TouchEvent,
+): void {
+  const touch = e.touches[0];
+  this._startX = touch?.clientX;
+  this._startY = touch?.clientY;
+} as HTMLDivElementWithDragObserver["ontouchstart"];

package/src/config/gui-options/scripts/forceDisableReactRemoveScroll.ts

@@ -0,0 +1,152 @@
+"use client";
+
+import type CookieConsent from "@tilli-pro/cookieconsent";
+
+// IMPORTANT: this is a fix to force-disable the "React Remove Scroll" wheel listener -- this handles the edge case where there's a shadcn (radix-ui) dialog open underneath the cookie banner's "manage preferences" dialog, which prevents the user from scrolling within the manage prefs dialog.
+
+/** IMPORTANT: this is what we'll be looking for in the listener's source code -- @see https://github.com/theKashey/react-remove-scroll/blob/master/src/SideEffect.tsx#L107-L145 */
+const DISTINCTIVE_SUBSTRINGS = ["shards", "noIsolation"];
+
+/** listener tracking */
+type ListenerRecord = {
+  type: "wheel" | "touchmove" | "touchstart" | "pointerdown" | "click";
+  listener: EventListenerOrEventListenerObject;
+  options?: boolean | AddEventListenerOptions;
+};
+
+const eventListenersMap = new WeakMap<EventTarget, ListenerRecord[]>();
+
+let isPatched = false; // ensure patching happens only ONCE.
+
+/** 🦧 monkey(orangutan)-patch `addEventListener` and `removeEventListener` to track listeners. */
+function patchEventListeners() {
+  if (isPatched) return; // prevent multiple patches
+  isPatched = true;
+
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  const originalAddEventListener = EventTarget.prototype.addEventListener;
+  EventTarget.prototype.addEventListener = function (
+    type: ListenerRecord["type"],
+    listener: ListenerRecord["listener"],
+    options?: ListenerRecord["options"],
+  ) {
+    let records = eventListenersMap.get(this);
+    if (!records) {
+      records = [];
+      eventListenersMap.set(this, records);
+    }
+    records.push({ type, listener, options });
+
+    originalAddEventListener.call(this, type, listener, options);
+  };
+
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  const originalRemoveEventListener = EventTarget.prototype.removeEventListener;
+  EventTarget.prototype.removeEventListener = function (
+    type: ListenerRecord["type"],
+    listener: ListenerRecord["listener"],
+    options?: ListenerRecord["options"],
+  ) {
+    const records = eventListenersMap.get(this);
+    if (records) {
+      const index = records.findIndex(
+        (r) =>
+          r.type === type && r.listener === listener && r.options === options,
+      );
+      if (index !== -1) {
+        records.splice(index, 1);
+        if (records.length === 0) eventListenersMap.delete(this);
+      }
+    }
+
+    originalRemoveEventListener.call(this, type, listener, options);
+  };
+}
+
+/** attempt to find the "React Remove Scroll" wheel listeners by searching for unique strings in its source code */
+const findReactRemoveScrollListeners = () =>
+  /** find all matching listeners that have ALL required substrings */
+  (eventListenersMap.get(document) ?? []).filter((record) => {
+    if (
+      record.type === "wheel" ||
+      record.type === "touchmove" ||
+      record.type === "touchstart" ||
+      record.type === "pointerdown" ||
+      record.type === "click"
+    ) {
+      const fnStr = record.listener.toString();
+      return DISTINCTIVE_SUBSTRINGS.every((sub) => fnStr.includes(sub));
+    }
+
+    return false;
+  });
+
+/**
+ * force the "React Remove Scroll" wheel listener to be passive or not.
+ *
+ * @param isPassive - Set `true` to make it `{ passive: true }`,
+ *                    `false` for `{ passive: false }`.
+ */
+export function forceDisableReactRemoveScroll(
+  isPassive: boolean,
+  debug = false,
+) {
+  const targets = findReactRemoveScrollListeners();
+  if (!targets || targets.length === 0) {
+    if (debug)
+      console.debug('No matching "React Remove Scroll" listener found.');
+    return;
+  }
+
+  /** remove the existing listener */
+  for (const target of targets) {
+    document.removeEventListener(
+      target.type,
+      target.listener,
+      target.options as EventListenerOptions,
+    );
+
+    /** re-add with the new passive value */
+    document.addEventListener(target.type, target.listener, {
+      ...(typeof target.options === "boolean" ? {} : target.options),
+      passive: isPassive,
+    });
+
+    if (debug)
+      console.debug(
+        `"React Remove Scroll" ${target.type} listener set to passive: ${isPassive} (aka, we've ${
+          isPassive ? "bypassed" : "re-enabled"
+        } it)`,
+      );
+  }
+}
+
+/**
+ * inject event listeners for CookieConsent's modal show/hide events,
+ * toggling the "React Remove Scroll" listener's passive state.
+ *
+ * listens for:
+ *  - "cc:onModalShow": If "preferencesModal", we set passive = true.
+ *  - "cc:onModalHide": If "preferencesModal", we set passive = false.
+ */
+export function injectReactRemoveScrollToggle(): void {
+  type OnModalShowHideEvent = CustomEvent<{
+    modalName: CookieConsent.ModalName;
+  }>;
+
+  patchEventListeners(); // ensure patching happens only once
+
+  window.addEventListener("cc:onModalShow", (event: Event) => {
+    const { detail } = (event as OnModalShowHideEvent | null) ?? {};
+
+    if (detail?.modalName === "preferencesModal")
+      forceDisableReactRemoveScroll(true); // force passive
+  });
+
+  window.addEventListener("cc:onModalHide", (event: Event) => {
+    const { detail } = (event as OnModalShowHideEvent | null) ?? {};
+
+    if (detail?.modalName === "preferencesModal")
+      forceDisableReactRemoveScroll(false); // force non-passive
+  });
+}

package/src/config/gui-options/scripts/injectManageCookiePrefsButton.ts

@@ -0,0 +1,50 @@
+"use client";
+
+import { showPreferences } from "@tilli-pro/cookieconsent";
+
+import type { HTMLDivElementWithDragObserver } from "./cookiePrefsButtonDragObserver";
+import ManageCookiePrefsButton, {
+  containerId,
+} from "../html-components/ManageCookiePrefsButton";
+import cookiePrefsButtonDragObserver, {
+  ontouchend,
+  ontouchstart,
+} from "./cookiePrefsButtonDragObserver";
+
+/** injects the floating cookie consent "manage preferences" icon button into the DOM */
+const inject = (): HTMLDivElement => {
+  const container = document.body.appendChild(
+    Object.assign(document.createElement("div"), {
+      id: containerId,
+      innerHTML: ManageCookiePrefsButton(/* TODO: __LANGUAGE__ */),
+      onclick:
+        showPreferences /** prefer over `data-cc="show-preferencesModal"` -- @see https://cookieconsent.orestbida.com/reference/api-reference.html#showpreferences */,
+      onmouseover: cookiePrefsButtonDragObserver,
+      // [mobile (touch) support]
+      ontouchend,
+      ontouchstart,
+    } satisfies Partial<HTMLDivElement>),
+  ) as HTMLDivElementWithDragObserver;
+
+  /** load drag observer upon DOM injection (unfortunate fix to prevent the need for 2x "ontouchstart" events) */
+  cookiePrefsButtonDragObserver.call(container);
+
+  return container;
+};
+export default (): ReturnType<typeof inject> =>
+  ((container) => {
+    /** observe the DOM (to handle the case where the injected manage prefs button somehow gets removed) */
+    new MutationObserver(() => {
+      const alreadyInjected: boolean =
+        !!document.getElementById(containerId) ||
+        document.body.contains(container);
+      if (alreadyInjected) return;
+
+      /** if the container is no longer in <body>, re-inject */
+      container = inject();
+    }).observe(document.body, { childList: true, subtree: true });
+
+    return container;
+  })(
+    (document.getElementById(containerId) as HTMLDivElement | null) ?? inject(),
+  );

package/src/config/index.ts

@@ -0,0 +1,15 @@
+import type { CookieConsentConfig } from "@tilli-pro/cookieconsent";
+
+import { COOKIE_PREFERENCES_COOKIE_NAME, REVISION } from "../_consts";
+import categories from "./categories";
+import guiOptions from "./gui-options";
+import translations from "./translations";
+
+export default {
+  revision: REVISION,
+  guiOptions,
+  categories,
+  language: { default: "en", autoDetect: "browser", translations },
+  cookie: { name: COOKIE_PREFERENCES_COOKIE_NAME },
+  hideFromBots: process.env.NODE_ENV === "production", // disabled in local dev to enable ui-testing (via Playwright)
+} satisfies CookieConsentConfig;