@mparticle/web-sdk 3.23.0 → 3.25.0

package/src/buttonTracking/buttonDescription.ts

@@ -1,18 +1,20 @@
 import { isFunction } from '../utils';
 import {
     hasComposedAncestor,
-    isUnsafeLabelSource,
     isUnsafeTextSource,
     isWalletElement,
+    nameWords,
+    someComposedAncestor,
 } from './controls';
-import { maskLabel } from './labelMasking';
+import { maskLabel, MAX_RAW_LABEL_LENGTH } from './labelMasking';
 
 // Describes a clicked button for auto button tracking: its masked name, icon,
 // hand-written identifiers and kind. Never reads form field values.
 export type ButtonElementKind = 'button' | 'input' | 'role' | 'wallet' | 'link';
 
-// The link clicks page views can't see: ones that stay on the page, leave the site or download a file.
-export type LinkType = 'same_page' | 'outbound' | 'download';
+// A same_page link acts as a button. The others leave the page: to another page
+// of the site, another site or a file.
+export type LinkType = 'same_page' | 'internal' | 'outbound' | 'download';
 
 const DOWNLOAD_EXTENSIONS = /\.(pdf|zip|csv|txt|ics|docx?|xlsx?|pptx?|dmg|exe|apk|mp3|mp4)$/i;
 
@@ -20,7 +22,6 @@ export type ButtonLabelSource =
     | 'labelledby'
     | 'aria'
     | 'text'
-    | 'label'
     | 'alt'
     | 'title'
     | 'value'
@@ -55,21 +56,155 @@ function elementKind(control: Element): ButtonElementKind {
     return control.matches('a[href]:not([role="button"])') ? 'link' : 'role';
 }
 
-function textOf(element: Element | null): string {
-    return element && !isUnsafeTextSource(element) && element.textContent
-        ? element.textContent.trim()
+const NOT_RENDERED =
+    'script, style, template, [hidden], [aria-hidden="true"], [inert]';
+
+// The most nodes read for one label source, and images looked at for one
+// button. Each costs a style lookup in the click handler.
+const MAX_READS = 64;
+
+function assignedNodes(element: Element): Node[] {
+    const slot = element as HTMLSlotElement;
+    return isFunction(slot.assignedNodes) ? slot.assignedNodes() : [];
+}
+
+// Left out of what is drawn by its parent: a light child of an open shadow host
+// that no slot takes, or a slot's own child while nodes are assigned to the
+// slot. A closed shadow root can't be seen, so its host's children count.
+function isUnslotted(node: Element | Text): boolean {
+    const parent = node.parentElement;
+    if (!parent) {
+        return false;
+    }
+    return parent.shadowRoot
+        ? !node.assignedSlot
+        : assignedNodes(parent).length > 0;
+}
+
+// Hides the element and all it holds, whatever their own style says.
+// Screen-reader-only text is clipped rather than hidden, so it is not. An SVG
+// title is never drawn but names its icon, so it is not either.
+function hidesSubtree(element: Element): boolean {
+    if (element.matches(NOT_RENDERED) || isUnslotted(element)) {
+        return true;
+    }
+    return (
+        !(element instanceof SVGTitleElement) &&
+        window.getComputedStyle(element).display === 'none'
+    );
+}
+
+// Visibility is inherited and a child can set it back to visible, so only the
+// element's own counts.
+function isVisible(element: Element): boolean {
+    const visibility = window.getComputedStyle(element).visibility;
+    return visibility !== 'hidden' && visibility !== 'collapse';
+}
+
+function isShown(element: Element, until?: Element): boolean {
+    return !someComposedAncestor(element, hidesSubtree, until);
+}
+
+// A shadow host shows a light child only through a slot, and only while
+// nothing from that slot up to the host hides it.
+function isShownThroughSlot(node: Element | Text, host: Element): boolean {
+    const slot = node.assignedSlot;
+    return !!slot && isShown(slot, host);
+}
+
+// Whitespace hides nothing, so a node holding only whitespace is taken as it
+// is, without a style lookup: an icon's paths cost nothing. A slot's text can
+// sit in the nodes assigned to it, so a slot is never blank.
+function isBlank(node: Element | Text): boolean {
+    return (
+        !/\S/.test(node.textContent || '') &&
+        !(
+            node instanceof Element &&
+            (node.matches('slot') || !!node.querySelector('slot'))
+        )
+    );
+}
+
+// The text a sighted user or a screen reader gets from an element, whitespace
+// collapsed. Undefined when that runs past what maskLabel keeps, takes more
+// than MAX_READS nodes to read, or takes in a form field through a slot, so a
+// label is never cut short at a node boundary.
+function renderedText(root: Element): string | undefined {
+    let text = '';
+    let reads = 0;
+    const append = (value: string) => {
+        text = (text + value).replace(/\s+/g, ' ');
+    };
+    const read = (element: Element): boolean => {
+        if (hidesSubtree(element)) {
+            return true;
+        }
+        const assigned = assignedNodes(element);
+        const nodes = assigned.length ? assigned : element.childNodes;
+        for (let i = 0; i < nodes.length; i++) {
+            const node = nodes[i] as Element | Text;
+            const isText = node.nodeType === Node.TEXT_NODE;
+            if (!isText && !(node instanceof Element)) {
+                continue;
+            }
+            if (isBlank(node)) {
+                append(node.textContent);
+                continue;
+            }
+            if (++reads > MAX_READS) {
+                return false;
+            }
+            if (element.shadowRoot && !isShownThroughSlot(node, element)) {
+                continue;
+            }
+            if (isText) {
+                if (isVisible(node.assignedSlot || element)) {
+                    append(node.nodeValue);
+                }
+            } else if (
+                // Assigned nodes sit outside the label source, where its own
+                // form field check never looked.
+                (assigned.length && isUnsafeTextSource(node as Element)) ||
+                !read(node as Element)
+            ) {
+                return false;
+            }
+            if (text.trim().length > MAX_RAW_LABEL_LENGTH) {
+                return false;
+            }
+        }
+        return true;
+    };
+    return read(root) ? text.trim() : undefined;
+}
+
+// '' when the element can't name the button, undefined when its text can't be
+// read in full.
+function textOf(element: Element | null): string | undefined {
+    return element && !isUnsafeTextSource(element) && isShown(element)
+        ? renderedText(element)
         : '';
 }
 
+// The control itself is already known to be shown.
+function shownImageAlt(control: Element): string | undefined {
+    const images = control.querySelectorAll('img[alt]');
+    for (let i = 0; i < images.length && i < MAX_READS; i++) {
+        if (isShown(images[i], control) && isVisible(images[i])) {
+            return nonBlank(images[i].getAttribute('alt'));
+        }
+    }
+    return undefined;
+}
+
 function nonBlank(value: string | null): string | undefined {
     return value && value.trim() ? value : undefined;
 }
 
 // The button's name as a screen reader would read it, simplified: the first of
-// aria-labelledby, aria-label, own text (or an inner image's alt), title, for
-// inputs their value, and for checkboxes and radios their label's text. The text
-// sources are skipped for controls that hold form fields or more than four
-// children, so a typed value is never read.
+// aria-labelledby, aria-label, own text (or an inner image's alt), title, and
+// for inputs their value. The text sources are skipped for controls that hold
+// form fields or more than four children, so a typed value is never read.
 function accessibleName(
     control: Element
 ): { raw?: string; source: ButtonLabelSource } {
@@ -78,13 +213,15 @@ function accessibleName(
         const root = (isFunction(control.getRootNode)
             ? control.getRootNode()
             : document) as Document | ShadowRoot;
-        const text = labelledBy
+        const parts = labelledBy
             .split(/\s+/)
             .map(id =>
                 textOf(root.getElementById ? root.getElementById(id) : null)
-            )
-            .filter(part => !!part)
-            .join(' ');
+            );
+        if (parts.indexOf(undefined) !== -1) {
+            return { source: 'none' };
+        }
+        const text = parts.filter(part => !!part).join(' ');
         if (text) {
             return { raw: text, source: 'labelledby' };
         }
@@ -112,24 +249,16 @@ function accessibleName(
                 // What the browser shows on an input without a value.
                 return { raw: type, source: 'value' };
             }
-        } else if (type === 'checkbox' || type === 'radio') {
-            // The label the browser ties to the box, never the box's value.
-            const label = control.labels ? control.labels[0] : undefined;
-            const text =
-                label && !isUnsafeLabelSource(label) && label.textContent
-                    ? label.textContent.trim()
-                    : '';
-            if (text) {
-                return { raw: text, source: 'label' };
-            }
         }
-    } else if (readable) {
-        const text = textOf(control);
+    } else if (readable && isShown(control)) {
+        const text = renderedText(control);
+        if (text === undefined) {
+            return { source: 'none' };
+        }
         if (text) {
             return { raw: text, source: 'text' };
         }
-        const image = control.querySelector('img[alt]');
-        const alt = image ? nonBlank(image.getAttribute('alt')) : undefined;
+        const alt = shownImageAlt(control);
         if (alt) {
             return { raw: alt, source: 'alt' };
         }
@@ -248,9 +377,12 @@ function formIdentifier(control: Element): string | undefined {
 }
 
 // The browser's normalised type: a button defaults to 'submit' and an unknown
-// input type reads as 'text'. Wallet and role buttons are just 'button'.
-function controlType(control: Element, element: ButtonElementKind): string {
-    return element === 'button' || element === 'input'
+// input type reads as 'text'. A native button or input reports its own type, a
+// wallet-named one included; any other control, such as a role button or a
+// vendor's wallet element, reads as 'button'.
+function controlType(control: Element): string {
+    const tag = control.tagName.toLowerCase();
+    return tag === 'button' || tag === 'input'
         ? (control as HTMLButtonElement | HTMLInputElement).type
         : 'button';
 }
@@ -262,8 +394,8 @@ interface ILinkDetails {
 }
 
 // Reads the link's own resolved URL parts, never its full href: only the hostname of
-// a link that leaves the site and the extension of a file it downloads travel. Navigation
-// within the site is left to page views, and mailto:, tel: and other schemes are skipped.
+// a link that leaves the site and the extension of a file it downloads travel.
+// mailto:, tel: and other schemes give undefined.
 function describeLink(link: Element): ILinkDetails | undefined {
     const href = (link.getAttribute('href') || '').trim();
     if (!href || href.charAt(0) === '#') {
@@ -297,13 +429,60 @@ function describeLink(link: Element): ILinkDetails | undefined {
     return link.pathname === window.location.pathname &&
         link.search === window.location.search
         ? { type: 'same_page' }
-        : undefined;
+        : { type: 'internal' };
+}
+
+// Whether a described click is on a link that leaves the page, logged as a link
+// click rather than a button click.
+export function isLinkClick(click: IButtonClick): boolean {
+    return !!click.linkType && click.linkType !== 'same_page';
+}
+
+// Checkboxes and radios, and the roles that act as them. A role can list
+// fallbacks, so any of its tokens counts.
+const CHOICE =
+    'input[type="checkbox"], input[type="radio"], [role~="checkbox"], [role~="radio"], ' +
+    '[role~="switch"], [role~="menuitemcheckbox"], [role~="menuitemradio"]';
+const RADIO_ROLE = '[role~="radio"], [role~="menuitemradio"]';
+
+function boxOf(element: Element): Element | null {
+    const box = element instanceof HTMLLabelElement ? element.control : element;
+    return box && box.matches(CHOICE) ? box : null;
+}
+
+function isRadio(choice: Element | null): boolean {
+    return choice instanceof HTMLInputElement
+        ? choice.type === 'radio'
+        : !!choice && choice.matches(RADIO_ROLE);
+}
+
+// The box a click on this control picks. One the click passed through below
+// the control comes first: querySelector can't reach a slotted box, a box in a
+// shadow root or the box of a label inside the control, and a row can hold
+// more than one box. Else the control itself, the box it labels, or the first
+// one it wraps, as on an option row whose name repeats the option's text.
+function choiceOf(
+    control: Element,
+    path: Array<EventTarget | null>
+): Element | null {
+    for (const target of path) {
+        if (target === control) {
+            break;
+        }
+        const box = target instanceof Element ? boxOf(target) : null;
+        if (box) {
+            return box;
+        }
+    }
+    return boxOf(control) || control.querySelector(CHOICE);
 }
 
-// Describes a clicked control for auto button tracking. A link counts only when page
-// views can't see the click, and carries its link type.
+// Describes a clicked control for auto button and link tracking. A link carries its
+// link type, and one to another scheme is skipped. A role="button" anchor carries one
+// only when it leaves the page; otherwise it stays a plain button.
 export function describeButtonClick(
-    control: Element
+    control: Element,
+    path: Array<EventTarget | null> = []
 ): IButtonClick | undefined {
     let link: ILinkDetails | undefined;
     if (control.matches('a[href]:not([role="button"])')) {
@@ -311,33 +490,137 @@ export function describeButtonClick(
         if (!link) {
             return undefined;
         }
+    } else if (control.matches('a[href]')) {
+        link = describeLink(control);
+        if (link && link.type === 'same_page') {
+            link = undefined;
+        }
     }
     const element = elementKind(control);
-    const name = accessibleName(control);
-    const label = maskLabel(name.raw);
+    const box =
+        control instanceof HTMLInputElement &&
+        (control.type === 'checkbox' || control.type === 'radio')
+            ? control
+            : undefined;
+    // A box's text sent with its state is the shopper's answer, and the text
+    // can be a name, an address or a sensitive choice, so a box goes by its
+    // hand-written identifiers alone. So does a control acting as one or
+    // wrapping one, and a label, whose click the browser passes on to its box
+    // as a second event.
+    const choice = box || choiceOf(control, path);
+    // A checkbox's identifiers name its question, which its state answers. A
+    // radio's id, test id and the panel it opens name the option picked, so
+    // only the name of its input, the question, goes with it. A wrapper's own
+    // name, or a role radio's, can name the option instead.
+    const radio = isRadio(choice);
+    const named = !radio
+        ? control
+        : choice instanceof HTMLInputElement
+        ? choice
+        : null;
+    const name = choice ? undefined : accessibleName(control);
+    const label = name ? maskLabel(name.raw) : undefined;
     return {
         label,
         labelSource: label ? name.source : 'none',
         // Kept on its own as well: it often says more than the visible text,
         // such as which item a remove button removes.
-        ariaLabel: maskLabel(control.getAttribute('aria-label')),
-        icon: iconHint(control),
-        elementId: stableIdentifier(control.getAttribute('id')),
-        elementName: stableIdentifier(control.getAttribute('name')),
-        testId: firstIdentifier(control, TEST_ID_ATTRIBUTES),
-        controls: controlsIdentifier(control),
+        ariaLabel: choice
+            ? undefined
+            : maskLabel(control.getAttribute('aria-label')),
+        icon: choice ? undefined : iconHint(control),
+        elementId: radio
+            ? undefined
+            : stableIdentifier(control.getAttribute('id')),
+        elementName: stableIdentifier(named && named.getAttribute('name')),
+        testId: radio
+            ? undefined
+            : firstIdentifier(control, TEST_ID_ATTRIBUTES),
+        controls: radio ? undefined : controlsIdentifier(control),
         form: formIdentifier(control),
         element,
-        type: controlType(control, element),
+        type: controlType(control),
         linkType: link ? link.type : undefined,
         linkDomain: link ? link.domain : undefined,
         fileExtension: link ? link.fileExtension : undefined,
         // The box as the click left it: the browser toggles it before the click
         // reaches listeners, and puts it back if the click is cancelled.
-        checked:
-            control instanceof HTMLInputElement &&
-            (control.type === 'checkbox' || control.type === 'radio')
-                ? control.checked
-                : undefined,
+        checked: box ? box.checked : undefined,
     };
 }
+
+// A question about payment, read from the names its author gave it, so
+// "checkout[payment_gateway]", "paymentMethod" and "tender_type" all count and
+// "payee" does not. A radio's input name is its question; its group or
+// fieldset speaks only for a radio with no name, as a role radio usually is.
+const PAYMENT_QUESTION = /(?:^| )(?:pay|payment\w*|tenders?|gateways?)(?: |$)/;
+const QUESTION_GROUP = '[role="radiogroup"], fieldset';
+
+function isPaymentQuestion(radio: Element): boolean {
+    const name = radio.getAttribute('name');
+    const group = name ? null : radio.closest(QUESTION_GROUP);
+    const question = group
+        ? [
+              group.getAttribute('id'),
+              group.getAttribute('name'),
+              group.getAttribute('aria-label'),
+          ]
+        : [name];
+    return question.some(words => PAYMENT_QUESTION.test(nameWords(words)));
+}
+
+// What names a payment option: the radio's accessible name, the text and
+// image of each label, and its hand-written ids, text masked like a label.
+function optionNames(radio: Element): string[] {
+    const names: Array<string | undefined> = [
+        maskLabel(accessibleName(radio).raw),
+    ];
+    const labels =
+        radio instanceof HTMLInputElement && radio.labels
+            ? Array.from(radio.labels).slice(0, 2)
+            : [];
+    labels.forEach(label => {
+        if (isShown(label) && !isUnsafeTextSource(label, radio)) {
+            names.push(maskLabel(renderedText(label)));
+            names.push(maskLabel(shownImageAlt(label)));
+        }
+    });
+    names.push(
+        stableIdentifier(radio.getAttribute('id')),
+        firstIdentifier(radio, TEST_ID_ATTRIBUTES)
+    );
+    return names.filter(
+        (name, index) => !!name && names.indexOf(name) === index
+    );
+}
+
+// The payment radio a click picks and the names of its option, for the Rokt
+// kit alone to read a payment method from. A radio's option is the shopper's
+// answer, so these names never go into the logged click.
+export interface IPaymentChoice {
+    radio: Element;
+    names: string[];
+}
+
+export function describePaymentChoice(
+    control: Element,
+    path: Array<EventTarget | null> = []
+): IPaymentChoice | undefined {
+    const choice = choiceOf(control, path);
+    if (
+        !isRadio(choice) ||
+        hasComposedAncestor(choice, '[data-mp-no-track]') ||
+        !isPaymentQuestion(choice)
+    ) {
+        return undefined;
+    }
+    const names = optionNames(choice);
+    return names.length ? { radio: choice, names } : undefined;
+}
+
+// Read once the page has handled the click, which may have cancelled it.
+export function isPicked(radio: Element): boolean {
+    return radio instanceof HTMLInputElement
+        ? radio.checked
+        : radio.getAttribute('aria-checked') === 'true';
+}