brut-js 0.0.9 → 0.0.11

package/src/Form.js

@@ -6,11 +6,19 @@ import ConstraintViolationMessages from "./ConstraintViolationMessages"
 /** A web component that enhances a form it contains to make constraint validations
  * easier to manage and control.
  *
- * The main feature this provides is to allow control the messaging of client-side constraint violations
- * beyond what the browser gives you. Assuming your `INPUT` tags are inside a container
- * like `LABEL`, a `brut-cv` tag found in that container
- * (i.e. a sibling of your `INPUT`) will be modified to contain error messages specific
- * to the {@link external:ValidityState} of the control.
+ * This provides two main features:
+ *
+ * * While the `:user-invalid` selector allows you to target inputs that have been interacted
+ *   with (thus avoiding issues when using `:invalid`), this still creates the experience of a
+ *   user tabbing off of a control and getting an error message.  If, instead, you only
+ *   want to show these errors when a submit has been attempted, this element will
+ *   set `submitted-invalid` on itself when that happens, thus allowing you to target invalid
+ *   fields only after a submission attempt.
+ * * You may wish to control the messaging of client-side constraint violations
+ *   beyond what the browser gives you. Assuming your `INPUT` tags are inside a container
+ *   like `LABEL`, a `brut-cv` tag found in that container
+ *   (i.e. a sibling of your `INPUT`) will be modified to contain error messages specific
+ *   to the {@link external:ValidityState} of the control.
  *
  * @fires brut:invalid Fired when any element is found to be invalid
  * @fires brut:valid Fired when no element is found to be invalid.  This should be reliable to know
@@ -29,17 +37,41 @@ import ConstraintViolationMessages from "./ConstraintViolationMessages"
  *       <brut-cv-messages>
  *       </brut-cv-messages>
  *     </div>
+ *     <button>Submit</button>
+ *   </form>
+ * </brut-form>
+ * <!-- after a submit of this form, the HTML will effectively be as follows -->
+ * <brut-form submitted-invalid>
+ *   <form ...>
+ *     <label>
+ *       <input type="text" required name="username">
+ *       <brut-cv-messages>
+ *         <brut-cv>This field is required</brut-cv>
+ *       </brut-cv-messages>
+ *     </label>
+ *     <div> <!-- container need not be a label -->
+ *       <input type="text" required minlength="4" name="alias">
+ *       <brut-cv-messages>
+ *         <brut-cv>This field is required</brut-cv>
+ *       </brut-cv-messages>
+ *     </div>
+ *     <button>Submit</button>
  *   </form>
  * </brut-form>
  *
+ * @property {boolean} submitted-invalid - set by this element when the form is submitted. Does not trigger any behavior and can be used in CSS.
  * @see ConstraintViolationMessages
  */
 class Form extends BaseCustomElement {
   static tagName = "brut-form"
   static observedAttributes = [
+    "submitted-invalid",
     "show-warnings",
   ]
 
+  #markFormSubmittedInvalid = (event) => {
+    this.setAttribute("submitted-invalid","")
+  }
   #updateValidity = (event) => {
     this.#updateErrorMessages(event)
   }
@@ -50,6 +82,8 @@ class Form extends BaseCustomElement {
     this.dispatchEvent(new CustomEvent("brut:invalid"))
   }
 
+  submittedInvalidChangedCallback() {}
+
   update() {
     const forms = this.querySelectorAll("form")
     if (forms.length == 0) {
@@ -59,6 +93,7 @@ class Form extends BaseCustomElement {
     forms.forEach( (form) => {
       Array.from(form.elements).forEach( (formElement) => {
         formElement.addEventListener("invalid", this.#updateValidity)
+        formElement.addEventListener("invalid", this.#markFormSubmittedInvalid)
         formElement.addEventListener("input", this.#updateValidity)
       })
       form.querySelectorAll(AjaxSubmit.tagName).forEach( (ajaxSubmits) => {

package/src/Tracing.js

@@ -0,0 +1,245 @@
+import { BaseCustomElement } from "brut-js"
+
+/** Sends performance data to an endpoint in a Brut-powered app that is expected to save it as an Open Telemetry span.
+ * Uses the W3C-recommended headers "traceparent" and "tracestate" to do this.
+ *
+ * ### Supported Metrics
+ *
+ * Currently, this will attempt to send "navigation", "largest-contentful-paint", and "first-contentful-paint" back to the server.
+ * Not all browsers support these, so this element will send back as many as it can.  It will wait for all supported metrics to be
+ * received before contacting the server. It will attempt to do this exactly once.
+ *
+ * ### Use
+ *
+ * To use this element, your page must have a `<meta>` element that contains the value for "traceparent".  It is expected that your
+ * server will include this in server-generatd HTML.  The Brut's `Brut::FrontEnd::Components::Traceparent` component will handle this
+ * for you. The value for "traceparent" is key to connecting the browser metrics to the back-end request that generated the page.
+ *
+ * The element also requires a `url` attribute to know where to send the data.  By default, Brut is listening in
+ * `/__brut/instrumentation`.  See the example.
+ *
+ * ### Durations vs Timestamps
+ *
+ * The performance API produces durations since an origin timestamp.  Open Telemetry wants timestamps.  In theory,
+ * `Performance.timeOrigin` is provided by the browser as a reference time when the page started doing anything.
+ * In practice, this value is incorrect on Firefox, so the element records a timestamp when it is created.
+ *
+ * When the data is merged back to the server span, the specific timestamps will not exactly match reality, however the durations will
+ * be accurate.  Note that even if `Performance.timeOrigin` was correct, clock drift between client and server would make
+ * the timestamps inaccurate anyway.
+ *
+ * ### Encoding
+ *
+ * The spec for the "tracestate" header leaves open how the data is to be encoded.  It supports multiple vendors using a key/value
+ * pair:
+ *
+ *     tracestate: honeycomb=«encoded data»,newrelic=«encoded data»
+ *
+ * This element uses the vendor name "brut". The data is a Base64-encoded JSON blob containing the data. 
+ *
+ *     tracestate: brut=«Base64 encoded JSON»
+ *
+ * The values captured and format of the JSON map closely to Open Telemetry's browser instrumentation format.
+ * Of course, this element is many magnitudes smaller in size than Open Telemetry's, which is why it exists at all
+ *
+ * @example
+ * <!DOCTYPE html>
+ * <html>
+ *   <head>
+ *     <meta name="traceparent" content="293874293749237439843294">
+ *     <brut-tracing url="/__brut/instrumentation"></brut-tracing>
+ *     <!-- ... -->
+ *   </head>
+ *   <body>
+ *     <!-- ... -->
+ *   </body>
+ * </html>
+ *
+ * @property {string} url - the url where the trace information is to be sent.
+ *
+ * @see {@link https://www.w3.org/TR/trace-context/}
+ * @see external:Performance
+ */
+class Tracing extends BaseCustomElement {
+  static tagName = "brut-tracing"
+
+  static observedAttributes = [
+    "url",
+    "show-warnings",
+  ]
+
+
+  #url            = null
+  #sent           = {}
+  #payload        = {}
+  #timeOrigin     = null
+  #supportedTypes = []
+
+  #performanceObserver = new PerformanceObserver( (entries) => {
+    const navigation = entries.getEntriesByType("navigation")[0]
+    if (navigation && navigation.loadEventEnd != 0 && !this.#payload.navigation) {
+      this.#payload.navigation = this.#parseNavigation(navigation)
+    }
+    const largestContentfulPaint = entries.getEntriesByType("largest-contentful-paint")
+    if (largestContentfulPaint.length > 0 && !this.#payload["largest-contentful-paint"]) {
+      this.#payload["largest-contentful-paint"] = this.#parseLargestContentfulPaint(largestContentfulPaint)
+    }
+    const paint = entries.getEntriesByName("first-contentful-paint", "paint")[0]
+    if (paint && !this.#payload.paint) {
+      this.#payload.paint = this.#parseFirstContentfulPaint(paint)
+    }
+
+    if ( this.#supportedTypes.every( (type) => this.#payload[type] ) ) {
+      this.#sendSpans()
+      this.#payload = {}
+    }
+  })
+
+  constructor() {
+    super()
+    this.#timeOrigin = Date.now()
+    this.#supportedTypes = [
+      "navigation",
+      "largest-contentful-paint",
+      "paint",
+    ].filter( (type) => {
+      return PerformanceObserver.supportedEntryTypes.includes(type)
+    })
+  }
+
+  urlChangedCallback({newValue}) {
+    this.#url = newValue
+  }
+
+  update() {
+    this.#supportedTypes.forEach( (type) => {
+      this.#performanceObserver.observe({type: type, buffered: true})
+    })
+  }
+
+  #sendSpans() {
+    const headers = this.#initializerHeadersIfCanContinue()
+    if (!headers) {
+      return
+    }
+    const span = this.#payload.navigation
+
+    if (this.#payload.paint) {
+      span.events.push({
+        name: this.#payload.paint.name,
+        timestamp: this.#timeOrigin + this.#payload.paint.startTime
+      })
+    }
+    if (this.#payload["largest-contentful-paint"]) {
+      this.#payload["largest-contentful-paint"].forEach( (event) => {
+        span.events.push({
+          name: event.name,
+          timestamp: this.#timeOrigin + event.startTime,
+          attributes: {
+            "element.tag": event.element?.tagName,
+            "element.class": event.element?.className,
+          }
+        })
+      })
+    }
+
+    this.#sent[this.#url] = true
+    headers.append("tracestate",`brut=${window.btoa(JSON.stringify(span))}`)
+    const request = new Request(
+      this.#url,
+      {
+        headers: headers,
+        method: "GET",
+      }
+    )
+    fetch(request).then( (response) => {
+      if (!response.ok) {
+        console.warn("Problem sending instrumentation: %s/%s", response.status,response.statusText)
+      }
+    }).catch( (error) => {
+      console.warn("Problem sending instrumentation: %o", error)
+    })
+  }
+
+  #parseNavigation(navigation) {
+    const documentFetch = {
+      name: "browser.documentFetch",
+      start_timestamp: navigation.fetchStart + this.#timeOrigin,
+      end_timestamp: navigation.responseEnd + this.#timeOrigin,
+      attributes: {
+        "http.url": navigation.name,
+      },
+    }
+    const events = [
+      "fetchStart",
+      "unloadEventStart",
+      "unloadEventEnd",
+      "domInteractive",
+      "domInteractive",
+      "domContentLoadedEventStart",
+      "domContentLoadedEventEnd",
+      "domComplete",
+      "loadEventStart",
+      "loadEventEnd",
+    ]
+
+    return {
+      name: "browser.documentLoad",
+      start_timestamp: navigation.fetchStart + this.#timeOrigin,
+      end_timestamp: navigation.loadEventEnd + this.#timeOrigin,
+      attributes: {
+        "http.url": navigation.name,
+        "http.user_agent": window.navigator.userAgent,
+      },
+      events: events.map( (eventName) => {
+        return {
+          name: eventName,
+          timestamp: this.#timeOrigin + navigation[eventName],
+        }
+      }),
+      spans: [
+        documentFetch
+      ]
+    }
+  }
+
+  #parseFirstContentfulPaint(paint) {
+    return {
+      name: "browser.first-contentful-paint",
+      startTime: paint.startTime,
+    }
+  }
+
+  #parseLargestContentfulPaint(largestContentfulPaint) {
+    return largestContentfulPaint.map( (entry) => {
+      return {
+        name: "browser.largest-contentful-paint",
+        startTime: entry.startTime,
+        element: entry.element,
+      }
+    })
+  }
+
+  #initializerHeadersIfCanContinue() {
+    if (!this.#url) {
+      this.logger.info("No url set, no traces will be reported")
+      return
+    }
+    const $traceparent = document.querySelector("meta[name='traceparent']")
+    if (!$traceparent) {
+      this.logger.info("No <meta name='traceparent' ...> in the document, no traces can be reported")
+      return
+    }
+    if (this.#sent[this.#url]) {
+      this.logger.info("Already sent to %s", this.#url)
+      return
+    }
+    const traceparent = $traceparent.getAttribute("content")
+    if (!traceparent) {
+      this.logger.info("%o had no value for the content attribute, no traces can be reported",$traceparent)
+      return
+    }
+    return new Headers({ traceparent })
+  }
+}
+export default Tracing

package/src/index.js

@@ -1,6 +1,6 @@
 import BaseCustomElement           from "./BaseCustomElement"
-import RichString                  from "./RichString"
 import AjaxSubmit                  from "./AjaxSubmit"
+import Autosubmit                  from "./Autosubmit"
 import ConfirmSubmit               from "./ConfirmSubmit"
 import ConfirmationDialog          from "./ConfirmationDialog"
 import ConstraintViolationMessage  from "./ConstraintViolationMessage"
@@ -8,10 +8,11 @@ import ConstraintViolationMessages from "./ConstraintViolationMessages"
 import CopyToClipboard             from "./CopyToClipboard"
 import Form                        from "./Form"
 import I18nTranslation             from "./I18nTranslation"
+import LocaleDetection             from "./LocaleDetection"
 import Message                     from "./Message"
+import RichString                  from "./RichString"
 import Tabs                        from "./Tabs"
-import LocaleDetection             from "./LocaleDetection"
-import Autosubmit                  from "./Autosubmit"
+import Tracing                     from "./Tracing"
 
 /**
  * This is the code for a test case. It may return a {@link external:Promise} if there is async behavior that must
@@ -39,6 +40,11 @@ import Autosubmit                  from "./Autosubmit"
  * })
  */
 
+/**
+ * @external Performance
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Performance|Performance API}
+ */
+
 /**
  * @external Promise
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise|Promise}
@@ -101,6 +107,7 @@ BrutCustomElements.addElementClasses(
   Tabs,
   LocaleDetection,
   Autosubmit,
+  Tracing,
 )
 
 export {
@@ -117,5 +124,6 @@ export {
   LocaleDetection,
   Message,
   RichString,
-  Tabs
+  Tabs,
+  Tracing
 }