@drevops/axel 0.0.0-stage → 0.1.1

package/src/core/core.js

@@ -0,0 +1,227 @@
+/**
+ * @file
+ * Axel core.
+ *
+ * Turns interactions with elements marked with 'data-axel-*' attributes into
+ * events and hands them to an adapter. README.md describes the attributes and
+ * the adapter contract.
+ */
+
+import { collectParams } from './dom.js';
+import { click } from './event-types/click.js';
+import { fieldComplete } from './event-types/field-complete.js';
+import { formStart } from './event-types/form-start.js';
+import { formSubmit } from './event-types/form-submit.js';
+
+export const TYPES = {
+  click,
+  form_start: formStart,
+  field_complete: fieldComplete,
+  form_submit: formSubmit,
+};
+
+export const DEFAULT_SETTINGS = {
+  // Event types to track, as keys of TYPES.
+  types: ['click'],
+  // An object with send(name, params, context) and an optional
+  // validate(name, params), or a function used as send().
+  adapter: null,
+  // Static parameters added to every event, overridden by all others.
+  properties: {},
+  // Elements whose clicks are tracked.
+  clickSelector: 'a[href], button, input[type="submit"], input[type="button"], input[type="reset"]',
+  // Headings that title a data-axel-group when it has no marker.
+  groupTitleSelector: 'h2, h3, h4',
+  // Functions named by data-axel-collector, as name => function.
+  collectors: {},
+  // Keep query strings and contact addresses in link_url and form_destination.
+  fullUrls: false,
+  debugHash: '#axel-debug',
+  debugStorageKey: 'axelDebug',
+  // Used by the standalone integration only.
+  autoInit: true,
+};
+
+export class Axel {
+  /**
+   * @param {object} settings - Overrides for DEFAULT_SETTINGS.
+   */
+  constructor(settings = {}) {
+    this.settings = { ...DEFAULT_SETTINGS, ...settings };
+
+    const { adapter } = this.settings;
+
+    this.adapter = typeof adapter === 'function' ? { send: adapter } : adapter;
+
+    if (typeof this.adapter?.send !== 'function') {
+      throw new Error('The analytics adapter must be a function or an object with a send() function.');
+    }
+
+    this.settings.types.forEach((type) => {
+      if (!Object.keys(TYPES).includes(type)) {
+        throw new Error(`Unknown analytics event type "${type}".`);
+      }
+    });
+
+    Object.entries(this.settings.collectors).forEach(([name, collector]) => {
+      if (typeof collector !== 'function') {
+        throw new Error(`The analytics collector "${name}" must be a function.`);
+      }
+    });
+
+    this.cleanups = null;
+  }
+
+  /**
+   * Start tracking the configured event types.
+   *
+   * Calling it again on an initialized instance does nothing.
+   *
+   * @return {Axel} The instance.
+   */
+  init() {
+    if (!this.cleanups) {
+      this.cleanups = this.settings.types.map((type) => TYPES[type](this));
+    }
+
+    return this;
+  }
+
+  /**
+   * Stop tracking. The instance can be initialized again afterwards.
+   */
+  destroy() {
+    this.cleanups?.forEach((cleanup) => cleanup());
+    this.cleanups = null;
+
+    if (shared === this) {
+      shared = null;
+    }
+  }
+
+  /**
+   * Send an event with the parameters of the element and its ancestors.
+   *
+   * @param {string}  name    - The event name.
+   * @param {Element} element - The element the event is about.
+   * @param {object}  derived - Parameters derived from the element, which
+   *   'data-axel-param-*' attributes override.
+   */
+  track(name, element, derived = {}) {
+    const params = { ...derived, ...collectParams(element) };
+
+    this.send(name, { ...params, ...this.collect(name, params, element) });
+  }
+
+  /**
+   * Run the collector named by the closest 'data-axel-collector'.
+   *
+   * A failing collector adds nothing, so the event is still sent.
+   *
+   * @param {string}  name    - The event name.
+   * @param {object}  params  - The event parameters, passed as a copy.
+   * @param {Element} element - The element the event is about.
+   * @return {object} The parameters the collector returns.
+   */
+  collect(name, params, element) {
+    const source = element.closest('[data-axel-collector]');
+
+    if (!source) {
+      return {};
+    }
+
+    const collectorName = source.getAttribute('data-axel-collector');
+
+    try {
+      // Only own keys, so a name such as 'toString' can't reach the prototype.
+      if (!Object.hasOwn(this.settings.collectors, collectorName)) {
+        throw new Error(`Unknown analytics collector "${collectorName}".`);
+      }
+
+      const collected = this.settings.collectors[collectorName](name, { ...params }, { element, source });
+
+      if (collected === undefined || collected === null) {
+        return {};
+      }
+
+      if (typeof collected !== 'object' || Array.isArray(collected)) {
+        throw new Error(`The analytics collector "${collectorName}" must return an object.`);
+      }
+
+      return collected;
+    } catch (error) {
+      console.error(`[axel] ${error.message}`);
+
+      return {};
+    }
+  }
+
+  /**
+   * Send a 'form_submit' event for a submission the server has confirmed.
+   *
+   * @param {string} formName - The form name.
+   * @param {object} params   - Additional parameters.
+   */
+  formSubmitted(formName, params = {}) {
+    this.send('form_submit', { form_name: formName, ...params });
+  }
+
+  /**
+   * Send an event to the adapter.
+   *
+   * @param {string} name   - The event name.
+   * @param {object} params - The event parameters.
+   */
+  send(name, params) {
+    const event = { ...this.settings.properties, ...params };
+    const debug = this.isDebug();
+
+    if (debug) {
+      console.log('[axel]', name, event);
+      (this.adapter.validate?.(name, event) || []).forEach((warning) => console.warn(`[axel] ${name}: ${warning}`));
+    }
+
+    this.adapter.send(name, event, { debug, settings: this.settings });
+  }
+
+  /**
+   * Check whether events are logged for debugging.
+   *
+   * The debug hash turns logging on until the browser tab closes, so it holds
+   * on the pages that clicks open.
+   *
+   * @return {boolean} TRUE if debugging.
+   */
+  isDebug() {
+    const { debugHash, debugStorageKey } = this.settings;
+    const requested = window.location.hash === debugHash;
+
+    try {
+      if (requested) {
+        window.sessionStorage.setItem(debugStorageKey, '1');
+      }
+
+      return requested || window.sessionStorage.getItem(debugStorageKey) === '1';
+    } catch {
+      // A browser that blocks storage throws on access.
+      return requested;
+    }
+  }
+}
+
+let shared = null;
+
+/**
+ * Initialize the shared instance.
+ *
+ * The first call creates the instance from the settings; later calls return it
+ * and ignore their settings.
+ *
+ * @param {object} settings - Overrides for DEFAULT_SETTINGS.
+ * @return {Axel} The shared instance.
+ */
+export function init(settings = {}) {
+  shared = shared || new Axel(settings);
+
+  return shared.init();
+}

package/src/core/dom.js

@@ -0,0 +1,153 @@
+/**
+ * @file
+ * DOM helpers shared by the event types.
+ */
+
+const PARAM_PREFIX = 'data-axel-param-';
+
+// The rest of a URL with these schemes is an address or a phone number.
+const CONTACT_PROTOCOLS = ['mailto:', 'tel:', 'sms:'];
+
+/**
+ * Add a capture-phase listener to the document.
+ *
+ * @param {string}   type    - The DOM event type.
+ * @param {Function} handler - The listener.
+ * @return {Function} A function that removes the listener.
+ */
+export function listen(type, handler) {
+  document.addEventListener(type, handler, true);
+
+  return () => document.removeEventListener(type, handler, true);
+}
+
+/**
+ * Get the text of a node, without what assistive technology skips.
+ *
+ * Form controls contribute no text, so a field value never ends up in a label.
+ *
+ * @param {Node} node - The node.
+ * @return {string} The text of the node and its descendants.
+ */
+export function getText(node) {
+  if (node.nodeType === Node.TEXT_NODE) {
+    return node.textContent;
+  }
+
+  if (node.nodeType !== Node.ELEMENT_NODE || node.getAttribute('aria-hidden') === 'true' || node.matches('select, textarea')) {
+    return '';
+  }
+
+  return [...node.childNodes].map(getText).join('');
+}
+
+/**
+ * Get the text that names an element in the reports.
+ *
+ * @param {Element} element - The element.
+ * @return {string} The text with whitespace collapsed, or the element's label
+ *   when it has no text.
+ */
+export function getLabel(element) {
+  // Only a button input's value is its label; any other input value is typed.
+  const isButton = element instanceof HTMLInputElement && ['submit', 'button', 'reset'].includes(element.type);
+  const value = isButton ? element.value : getText(element);
+
+  return value.replace(/\s+/g, ' ').trim() || element.getAttribute('aria-label') || element.getAttribute('title') || '';
+}
+
+/**
+ * Collect the 'data-axel-param-*' values of the element and its ancestors.
+ *
+ * @param {Element} element - The element to start from.
+ * @return {object} The parameters, the closest of each name winning.
+ */
+export function collectParams(element) {
+  const params = {};
+
+  for (let node = element; node; node = node.parentElement) {
+    [...node.attributes]
+      .filter((attribute) => attribute.name.startsWith(PARAM_PREFIX))
+      .forEach((attribute) => {
+        const name = attribute.name.slice(PARAM_PREFIX.length).replace(/-/g, '_');
+
+        if (params[name] === undefined) {
+          params[name] = attribute.value;
+        }
+      });
+  }
+
+  return params;
+}
+
+/**
+ * Check if the element or an ancestor opts out of tracking.
+ *
+ * @param {Element} element - The element.
+ * @return {boolean} TRUE if the element is skipped.
+ */
+export function isSkipped(element) {
+  return element.closest('[data-axel-skip]') !== null;
+}
+
+/**
+ * Resolve a URL attribute of an element against the page.
+ *
+ * The attribute is read directly because a form field named like a form
+ * property, such as 'action' or 'id', shadows that property on the form.
+ *
+ * Unless 'fullUrl' is set, the query string is dropped and a 'mailto:', 'tel:'
+ * or 'sms:' URL is reduced to its scheme, because both often hold personal
+ * information.
+ *
+ * @param {Element} element   - The element.
+ * @param {string}  attribute - The attribute name.
+ * @param {boolean} fullUrl   - Whether to keep the URL as it is.
+ * @return {string|undefined} The absolute URL, or undefined when the value
+ *   isn't a valid URL.
+ */
+export function resolveUrl(element, attribute, fullUrl = false) {
+  let url;
+
+  try {
+    url = new URL(element.getAttribute(attribute), element.baseURI);
+  } catch {
+    return undefined;
+  }
+
+  if (fullUrl) {
+    return url.href;
+  }
+
+  if (CONTACT_PROTOCOLS.includes(url.protocol)) {
+    return url.protocol;
+  }
+
+  url.search = '';
+
+  return url.href;
+}
+
+/**
+ * Get the parameters that describe a marked form.
+ *
+ * @param {Element} form    - The element with 'data-axel-form'.
+ * @param {boolean} fullUrl - Whether to keep the destination URL as it is.
+ * @return {object} The form name, and the form ID and destination when known.
+ */
+export function formParams(form, fullUrl = false) {
+  const params = { form_name: form.getAttribute('data-axel-form') };
+  const id = form.getAttribute('id');
+
+  if (id) {
+    params.form_id = id;
+  }
+
+  const destination = form instanceof HTMLFormElement && form.hasAttribute('action') ? resolveUrl(form, 'action', fullUrl) : undefined;
+
+  if (destination !== undefined) {
+    params.form_destination = destination;
+  }
+
+  return params;
+}

package/src/core/event-types/click.js

@@ -0,0 +1,130 @@
+/**
+ * @file
+ * Click events for interactive elements inside 'data-axel-event'.
+ */
+
+import { getLabel, isSkipped, listen, resolveUrl } from '../dom.js';
+
+/**
+ * Find the title closest before an element within a scope.
+ *
+ * A match counts when it precedes the element in document order and is not
+ * one of its ancestors, so the lookup covers the element's preceding siblings
+ * and its ancestors' preceding siblings up to the scope.
+ *
+ * @param {Element} element  - The element.
+ * @param {Element} scope    - The element that bounds the lookup.
+ * @param {string}  selector - The CSS selector of the titles.
+ * @return {Element|undefined} The last matching title, if any.
+ */
+function findTitle(element, scope, selector) {
+  return [...scope.querySelectorAll(selector)]
+    .filter((title) => title.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_FOLLOWING && !title.contains(element) && !isSkipped(title))
+    .pop();
+}
+
+/**
+ * Get the title of the closest group or subgroup around an element.
+ *
+ * @param {Element}  element   - The element.
+ * @param {string}   kind      - 'group' or 'subgroup'.
+ * @param {string[]} selectors - The CSS selectors of the titles, in order of
+ *   priority.
+ * @return {string|undefined} The title, an empty string when none matches, or
+ *   undefined outside any group of the kind.
+ */
+function getGroupTitle(element, kind, selectors) {
+  const group = element.closest(`[data-axel-${kind}]`);
+
+  if (!group) {
+    return undefined;
+  }
+
+  const scopeSelector = group.getAttribute(`data-axel-${kind}-scope`);
+  const scope = (scopeSelector && group.closest(scopeSelector)) || group;
+
+  for (const selector of selectors) {
+    const title = findTitle(element, scope, selector);
+
+    if (title) {
+      return getLabel(title);
+    }
+  }
+
+  return '';
+}
+
+/**
+ * Get the address a submit button sends its form to.
+ *
+ * @param {Element} element - The element.
+ * @param {boolean} fullUrl - Whether to keep the address as it is.
+ * @return {string|undefined} The absolute address, if the element is a submit
+ *   button with a valid 'formaction' or a form with a valid 'action'.
+ */
+function getSubmitDestination(element, fullUrl) {
+  if (element.type !== 'submit' || !element.form) {
+    return undefined;
+  }
+
+  if (element.hasAttribute('formaction')) {
+    return resolveUrl(element, 'formaction', fullUrl);
+  }
+
+  return element.form.hasAttribute('action') ? resolveUrl(element.form, 'action', fullUrl) : undefined;
+}
+
+/**
+ * Track clicks and middle clicks.
+ *
+ * @param {import('../core.js').Axel} axel - The instance.
+ * @return {Function} A function that stops tracking.
+ */
+export function click(axel) {
+  const track = (event) => {
+    const element = event.target instanceof Element ? event.target.closest(axel.settings.clickSelector) : null;
+
+    if (!element || isSkipped(element)) {
+      return;
+    }
+
+    const enrolled = element.closest('[data-axel-event]');
+
+    if (!enrolled) {
+      return;
+    }
+
+    const isLink = element instanceof HTMLAnchorElement;
+    const params = { link_text: getLabel(element), click_type: isLink ? 'link' : 'button' };
+    const { fullUrls } = axel.settings;
+    const linkUrl = isLink ? resolveUrl(element, 'href', fullUrls) : getSubmitDestination(element, fullUrls);
+
+    if (linkUrl !== undefined) {
+      params.link_url = linkUrl;
+    }
+
+    const groupTitle = getGroupTitle(element, 'group', ['[data-axel-group-title]', axel.settings.groupTitleSelector]);
+
+    if (groupTitle !== undefined) {
+      params.group_title = groupTitle;
+    }
+
+    const subgroupTitle = getGroupTitle(element, 'subgroup', ['[data-axel-subgroup-title]']);
+
+    if (subgroupTitle !== undefined) {
+      params.subgroup_title = subgroupTitle;
+    }
+
+    axel.track(enrolled.getAttribute('data-axel-event'), element, params);
+  };
+
+  // Capture runs before any handler on the page can stop a click from
+  // reaching the document.
+  const removers = [
+    listen('click', track),
+    // A middle click opens a link in a new tab and fires only 'auxclick'.
+    listen('auxclick', (event) => event.button === 1 && track(event)),
+  ];
+
+  return () => removers.forEach((remove) => remove());
+}

package/src/core/event-types/field-complete.js

@@ -0,0 +1,49 @@
+/**
+ * @file
+ * The 'field_complete' event for a changed field inside a marked form.
+ */
+
+import { formParams, getText, isSkipped, listen } from '../dom.js';
+
+/**
+ * Get the label of a field without its value.
+ *
+ * An option's label is the answer, so radios and checkboxes in a fieldset are
+ * named by the fieldset legend, and a radio never by its own label.
+ *
+ * @param {Element} field - The field.
+ * @return {string} The label, or an empty string.
+ */
+function getFieldLabel(field) {
+  const legend = ['checkbox', 'radio'].includes(field.type) ? field.closest('fieldset')?.querySelector(':scope > legend') : null;
+  const label = legend || (field.type === 'radio' ? null : field.labels?.[0]);
+
+  return (label ? getText(label).replace(/\s+/g, ' ').trim() : '') || field.getAttribute('aria-label') || '';
+}
+
+/**
+ * Track changes to fields inside marked forms.
+ *
+ * @param {import('../core.js').Axel} axel - The instance.
+ * @return {Function} A function that stops tracking.
+ */
+export function fieldComplete(axel) {
+  return listen('change', (event) => {
+    const field = event.target;
+    const form = field instanceof Element ? field.closest('[data-axel-form]') : null;
+
+    if (!form || isSkipped(field)) {
+      return;
+    }
+
+    const params = formParams(form, axel.settings.fullUrls);
+
+    if (field.name) {
+      params.field_name = field.name;
+    }
+
+    params.field_label = getFieldLabel(field);
+
+    axel.track('field_complete', field, params);
+  });
+}

package/src/core/event-types/form-start.js

@@ -0,0 +1,27 @@
+/**
+ * @file
+ * The 'form_start' event for the first focus inside a marked form.
+ */
+
+import { formParams, isSkipped, listen } from '../dom.js';
+
+/**
+ * Track the first focus inside each marked form.
+ *
+ * @param {import('../core.js').Axel} axel - The instance.
+ * @return {Function} A function that stops tracking.
+ */
+export function formStart(axel) {
+  const started = new WeakSet();
+
+  return listen('focusin', (event) => {
+    const form = event.target instanceof Element ? event.target.closest('[data-axel-form]') : null;
+
+    if (!form || started.has(form) || isSkipped(event.target)) {
+      return;
+    }
+
+    started.add(form);
+    axel.track('form_start', form, formParams(form, axel.settings.fullUrls));
+  });
+}

package/src/core/event-types/form-submit.js

@@ -0,0 +1,45 @@
+/**
+ * @file
+ * The 'form_submit' event for server-rendered confirmation markers.
+ */
+
+import { isSkipped } from '../dom.js';
+
+const MARKER = '[data-axel-form-submitted]';
+
+/**
+ * Track confirmation markers present at start and added later.
+ *
+ * @param {import('../core.js').Axel} axel - The instance.
+ * @return {Function} A function that stops tracking.
+ */
+export function formSubmit(axel) {
+  const seen = new WeakSet();
+
+  const report = (marker) => {
+    if (seen.has(marker) || isSkipped(marker)) {
+      return;
+    }
+
+    seen.add(marker);
+    axel.track('form_submit', marker, { form_name: marker.getAttribute('data-axel-form-submitted') });
+  };
+
+  const scan = (root) => {
+    if (root.matches?.(MARKER)) {
+      report(root);
+    }
+
+    root.querySelectorAll(MARKER).forEach(report);
+  };
+
+  // AJAX forms render the confirmation after the page has loaded.
+  const observer = new MutationObserver((records) => {
+    records.forEach((record) => record.addedNodes.forEach((node) => node instanceof Element && scan(node)));
+  });
+
+  observer.observe(document, { childList: true, subtree: true });
+  scan(document);
+
+  return () => observer.disconnect();
+}

package/src/index.js

@@ -0,0 +1,8 @@
+/**
+ * @file
+ * ES module entry point.
+ */
+
+export { Axel, DEFAULT_SETTINGS, TYPES, init } from './core/core.js';
+export { gtag } from './adapters/gtag.js';
+export { gtm } from './adapters/gtm.js';

package/src/integrations/drupal.js

@@ -0,0 +1,31 @@
+/**
+ * @file
+ * Drupal integration: starts in a behavior from 'drupalSettings'.
+ */
+
+import { Axel, init } from '../core/core.js';
+
+/**
+ * Register the 'axel' behavior and expose the class on 'window'.
+ *
+ * The behavior initializes the shared instance from 'drupalSettings.axel' and
+ * exposes it as 'window.axel'. 'drupalSettings' can't hold functions, so the
+ * collectors come from 'window.axelCollectors'.
+ *
+ * @param {object} [adapter] - The adapter. Defaults to 'window.axelAdapter' as
+ *   defined when the behavior attaches.
+ */
+export function start(adapter) {
+  window.Axel = Axel;
+
+  window.Drupal.behaviors.axel = {
+    // Listeners are delegated to the document and init() is idempotent, so
+    // every attach after the first, including AJAX ones, is a no-op.
+    attach() {
+      const settings = window.drupalSettings.axel;
+      const collectors = { ...window.axelCollectors, ...settings?.collectors };
+
+      window.axel = init({ ...settings, collectors, adapter: adapter || window.axelAdapter });
+    },
+  };
+}

package/src/integrations/standalone.js

@@ -0,0 +1,27 @@
+/**
+ * @file
+ * Standalone integration: starts on load from page settings.
+ */
+
+import { Axel, init } from '../core/core.js';
+
+/**
+ * Initialize from 'window.axelSettings' unless 'autoInit' is false, and expose
+ * the class and the instance on 'window'.
+ *
+ * The collectors in 'window.axelCollectors' are added to the collectors in the
+ * settings.
+ *
+ * @param {object} [adapter] - The adapter. Defaults to 'window.axelAdapter'.
+ */
+export function start(adapter) {
+  const pageSettings = window.axelSettings;
+  const collectors = { ...window.axelCollectors, ...pageSettings?.collectors };
+  const settings = { ...pageSettings, collectors, adapter: adapter || window.axelAdapter };
+
+  window.Axel = Axel;
+
+  // Listeners are delegated to the document, so the DOM does not need to be
+  // ready and clicks are tracked before other scripts load.
+  window.axel = settings.autoInit === false ? new Axel(settings) : init(settings);
+}