✨ [RUMF-385] implement a declarative API to set the action names

packages/rum/README.md

@@ -71,6 +71,18 @@ datadogRum.init({
   addUserAction (name: string, context: Context)
   ```
 
+## Declarative API
+
+### Click action naming
+
+The RUM library will use various strategies to get a name for click actions, but if you want more
+control, you can define a `data-dd-action-name` attribute on clickable elements (or any of their
+parents) that will be used to name the action. Example:
+
+```html
+<a class="btn btn-default" href="#" role="button" data-dd-action-name="Login button">Try it out!</a>
+```
+
 ## TypeScript support
 
 Types are compatible with TypeScript >= 3.0.

packages/rum/src/getActionNameFromElement.ts

@@ -1,16 +1,48 @@
 export function getActionNameFromElement(element: Element): string {
   // Proceed to get the action name in two steps:
-  // * first, use strategies that are known to return good results. Those strategies will be used on
+  // * first, get the name programmatically, explicitely defined by the user.
+  // * then, use strategies that are known to return good results. Those strategies will be used on
   //   the element and a few parents, but it's likely that they won't succeed at all.
   // * if no name is found this way, use strategies returning less accurate names as a fallback.
   //   Those are much likely to succeed.
   return (
+    getActionNameFromElementProgrammatically(element) ||
     getActionNameFromElementForGetters(element, priorityGetters) ||
     getActionNameFromElementForGetters(element, fallbackGetters) ||
     ''
   )
 }
 
+/**
+ * Get the action name from the attribute 'data-dd-action-name' on the element or any of its parent.
+ */
+const PROGRAMMATIC_ATTRIBUTE = 'data-dd-action-name'
+function getActionNameFromElementProgrammatically(targetElement: Element) {
+  let elementWithAttribute
+  // We don't use getActionNameFromElementForGetters here, because we want to consider all parents,
+  // without limit. It is up to the user to declare a relevent naming strategy.
+  // If available, use element.closest() to match get the attribute from the element or any of its
+  // parent.  Else fallback to a more traditional implementation.
+  if (supportsElementClosest()) {
+    elementWithAttribute = targetElement.closest(`[${PROGRAMMATIC_ATTRIBUTE}]`)
+  } else {
+    let element: Element | null = targetElement
+    while (element) {
+      if (element.hasAttribute(PROGRAMMATIC_ATTRIBUTE)) {
+        elementWithAttribute = element
+        break
+      }
+      element = element.parentElement
+    }
+  }
+
+  if (!elementWithAttribute) {
+    return
+  }
+  const name = elementWithAttribute.getAttribute(PROGRAMMATIC_ATTRIBUTE)!
+  return truncate(normalizeWhitespace(name.trim()))
+}
+
 type NameGetter = (element: Element | HTMLElement | HTMLInputElement | HTMLSelectElement) => string | undefined | null
 
 const priorityGetters: NameGetter[] = [
@@ -181,3 +213,17 @@ function supportsLabelProperty() {
   }
   return supportsLabelPropertyResult
 }
+
+/**
+ * Returns true if the browser supports the element.closest method.  This should be the case
+ * everywhere except on Internet Explorer.
+ * Note: The result is computed lazily, because we don't want any DOM access when the SDK is
+ * evaluated.
+ */
+let supportsElementClosestResult: boolean | undefined
+function supportsElementClosest() {
+  if (supportsElementClosestResult === undefined) {
+    supportsElementClosestResult = 'closest' in HTMLElement.prototype
+  }
+  return supportsElementClosestResult
+}

packages/rum/test/getActionNameFromElement.spec.ts

@@ -244,4 +244,47 @@ describe('getActionNameFromElement', () => {
       `)
     ).toBe('foo')
   })
+
+  describe('programmatically declared action name', () => {
+    it('extracts the name from the data-dd-action-name attribute', () => {
+      expect(
+        getActionNameFromElement(element`
+          <div data-dd-action-name="foo">ignored</div>
+        `)
+      ).toBe('foo')
+    })
+
+    it('considers any parent', () => {
+      const target = element`
+        <form>
+          <i><i><i><i><i><i><i><i><i><i><i><i>
+            <span target>ignored</span>
+          </i></i></i></i></i></i></i></i></i></i></i></i>
+        </form>
+      `
+      // Set the attribute on the <HTML> element
+      target.ownerDocument!.documentElement.setAttribute('data-dd-action-name', 'foo')
+      expect(getActionNameFromElement(target)).toBe('foo')
+    })
+
+    it('normalizes the value', () => {
+      expect(
+        getActionNameFromElement(element`
+          <div data-dd-action-name="   foo  \t bar  ">ignored</div>
+        `)
+      ).toBe('foo bar')
+    })
+
+    it('fallback on an automatic strategy if the attribute is empty', () => {
+      expect(
+        getActionNameFromElement(element`
+          <div data-dd-action-name="ignored">
+            <div data-dd-action-name="">
+              <span target>foo</span>
+            </div>
+          </div>
+      `)
+      ).toBe('foo')
+    })
+  })
 })