brut 0.0.20 → 0.0.22

data/brut-js/src/RichString.js

@@ -0,0 +1,113 @@
+/** A wrapper around a string that provides useful utility functions
+ * not present in the standard library.
+ *
+ * @example
+ *
+ * const string = RichString.fromString(element.textContent)
+ * element.textContent = string.humanize().toString()
+ */
+class RichString {
+  /** Prefer this over the constructor, as this will
+   * wrap `possiblyDefinedStringOrRichString` only if necessary
+   * as well as handle `null`.
+   *
+   * @param {null|undefined|String|RichString} possiblyDefinedStringOrRichString - if `null`, `undefined`, or otherwise falsey, this method returns `null`. If a String, returns a new `RichString` wrapping it. If a `RichString`, returns the `RichString` unchanged.
+   */
+  static fromString(possiblyDefinedStringOrRichString) {
+    if (possiblyDefinedStringOrRichString instanceof RichString) {
+      return possiblyDefinedStringOrRichString
+    }
+    if (!possiblyDefinedStringOrRichString) {
+      return null
+    }
+    return new RichString(String(possiblyDefinedStringOrRichString))
+  }
+
+  /** Prefer `fromString` */
+  constructor(string) {
+    if (typeof string !== "string") {
+      throw `You may only construct a RichString with a String, not a ${typeof string}`
+    }
+    this.string = string
+  }
+
+  /** Returns a `RichString` with the string capitalized. */
+  capitalize() {
+    return new RichString(this.string.charAt(0).toUpperCase() + this.string.slice(1))
+  }
+
+  /** Returns a `RichString` with the string un-capitalized. */
+  decapitalize() {
+    return new RichString(this.string.charAt(0).toLowerCase() + this.string.slice(1))
+  }
+
+  /** Returns a `RichString` with the string converted from snake or kebab case into camel case. */
+  camelize() {
+    // Taken from camelize npm module
+    return RichString.fromString(this.string.replace(/[_.-](\w|$)/g, function (_, x) {
+      return x.toUpperCase()
+    }))
+  }
+
+  /** Returns a 'humanized' `RichString`, which is basically a de-camelized version with the first letter
+   * capitalized.
+   */
+  humanize() {
+    return this.decamlize({spacer: " "}).capitalize()
+  }
+
+  /** Returns a `RichString` with the string converted from camel case to snake or kebab case.
+    *
+    * @param {Object} parameters
+    * @param {string} parameters.spacer ["_"] - a string to use when joining words together.
+    *
+    */
+  decamlize({spacer="_"} = {}) {
+    // Taken from decamelize NPM module
+
+    // Checking the second character is done later on. Therefore process shorter strings here.
+    if (this.string.length < 2) {
+      return new RichString(this.string.toLowerCase())
+    }
+
+    const replacement = `$1${spacer}$2`
+
+    // Split lowercase sequences followed by uppercase character.
+    // `dataForUSACounties` → `data_For_USACounties`
+    // `myURLstring → `my_URLstring`
+    const decamelized = this.string.replace(
+      /([\p{Lowercase_Letter}\d])(\p{Uppercase_Letter})/gu,
+      replacement,
+    )
+
+    // Split multiple uppercase characters followed by one or more lowercase characters.
+    // `my_URLstring` → `my_ur_lstring`
+    return new RichString(decamelized.
+      replace(
+        /(\p{Uppercase_Letter})(\p{Uppercase_Letter}\p{Lowercase_Letter}+)/gu,
+        replacement,
+      ).
+      toLowerCase()
+    )
+  }
+
+  /** Return the underlying String value */
+  toString() { return this.string }
+
+  /** Return the underlying String value or null if the string is blank */
+  toStringOrNull() {
+    if (this.isBlank()) {
+      return null
+    }
+    else {
+      return this.string
+    }
+  }
+
+  /* Returns true if this string has only whitespace in it */
+  isBlank() {
+    return this.string.trim() == ""
+  }
+
+}
+export default RichString

data/brut-js/src/Tabs.js

@@ -0,0 +1,168 @@
+import BaseCustomElement from "./BaseCustomElement"
+
+/** Implements an in-page tab selector.  It's intended to wrap a set of `<a>` or `<button>` elements
+ * that represent the tabs of a tabbed UI, as defined by ARIA roles.  
+ *
+ * Each direct child must be an `<a>` or a `<button>`, though `<a>` is recommended.
+ * Any other elements are ignored.  Each `<a>` or `<button>`
+ * (herafter referred to as "tab") must have the correct ARIA attributes:
+ *
+ * * `role="tab"`
+ * * `aria-selected` as true or false, depending on what tab is selected when the page is first rendered.  This
+ *   custom element will ensure this value is updated as different tabs are selected.
+ * * `tabindex` should be 0 if selected, -1 otherwise. This custom element will ensure this value is updated as
+ *   different tabs are selected.
+ * * `aria-controls` to the ID or list of IDs of panels that should be shown when this tab is selected.
+ * * `id` to allow the `tab-panel` to refer back to this tab.
+ *
+ * This custom element will set click listeners on all tabs and, when clicked, hide all panels referred to by
+ * every tab (by setting the `hidden` attribute), then show only those panels referred to by the clicked
+ * tab.  You can use CSS to style everything the way you like it.
+ *
+ * @property {boolean} tab-selection-pushes-and-restores-state if set, this custom element will use the 
+ *                                                             history API to manage state. When a tab
+ *                                                             implemented by an `<a>` with an `href` is
+ *                                                             clicked, that `href` will be pushed into 
+ *                                                             the state.  When the back button is hit,
+ *                                                             this will select the previous tab as selected.
+ *                                                             Note that this will conflict with anything else
+ *                                                             on the page that manipulates state, so only
+ *                                                             set this if your UI is a "full page tab"
+ *                                                             style UI.
+ *
+ * @fires Tabs#brut:tabselected whenever the tab selection has changed
+ * @example
+ * <brut-tabs>
+ *   <a role="tab" aria-selected="true"  tabindex="0"  aria-controls="inbox-panel"  id="inbox-tab"
+ *      href="?tab=inbox">Inbox</a>
+ *   <a role="tab" aria-selected="false" tabindex="-1" aria-controls="drafts-panel" id="drafts-tab"
+ *      href="?tab=drafts">Drafts</a>
+ *   <a role="tab" aria-selected="false" tabindex="-1" aria-controls="spam-panel"   id="spam-tab"
+ *      href="?tab=spam">Spam</a>
+ * </brut-tabs>
+ * <section role="tabpanel" tabindex="0"  id="inbox-panel">
+ *   <h3>Inbox</h3>
+ * </section>
+ * <section role="tabpanel" tabindex="0" id="drafts-panel" hidden>
+ *   <h3>Drafts</h3>
+ * </section>
+ * <section role="tabpanel" tabindex="0" id="spam-panel"   hidden>
+ *   <h3>Spam</h3>
+ * </section>
+ * <!-- if a user clicks on 'Drafts', the DOM will be updated to look
+ *      effectively like so: -->
+ * <brut-tabs>
+ *   <a role="tab" aria-selected="false" tabindex="-1" aria-controls="inbox-panel"  id="inbox-tab"
+ *      href="?tab=inbox">Inbox</a>
+ *   <a role="tab" aria-selected="true"  tabindex="0"  aria-controls="drafts-panel" id="drafts-tab"
+ *      href="?tab=drafts">Drafts</a>
+ *   <a role="tab" aria-selected="false" tabindex="-1" aria-controls="spam-panel"   id="spam-tab"
+ *      href="?tab=spam">Spam</a>
+ * </brut-tabs>
+ * <section role="tabpanel" tabindex="0"  id="inbox-panel"  hidden>
+ *   <h3>Inbox</h3>
+ * </section>
+ * <section role="tabpanel" tabindex="-1" id="drafts-panel">
+ *   <h3>Drafts</h3>
+ * </section>
+ * <section role="tabpanel" tabindex="-1" id="spam-panel"   hidden>
+ *   <h3>Spam</h3>
+ * </section>
+ *
+ * @customElement brut-tabs
+ */
+class Tabs extends BaseCustomElement {
+  static tagName = "brut-tabs"
+  static observedAttributes = [
+    "tab-selection-pushes-and-restores-state",
+    "show-warnings",
+  ]
+
+  tabSelectionPushesAndRestoresStateChangedCallback({newValue,oldValue}) {
+    this.#pushAndRestoreTabState = newValue != null
+  }
+
+  update() {
+    this.#tabs().forEach( (tab) => {
+      tab.addEventListener("click", this.#tabClicked)
+    })
+  }
+
+  #pushAndRestoreTabState = false
+
+  #tabClicked = (event) => {
+    event.preventDefault()
+    this.#setTabAsSelected(event.target)
+    event.preventDefault()
+  }
+
+  #reloadTab = (event) => {
+    const tab = document.getElementById(event.state.tabId)
+    if (tab) {
+      this.#setTabAsSelected(tab, { skipPushState: true })
+    }
+  }
+
+  #setTabAsSelected(selectedTab, { skipPushState = false } = {}) {
+    this.#tabs().forEach( (tab) => {
+      const tabPanels = []
+      const ariaControls = tab.getAttribute("aria-controls")
+      if (ariaControls) {
+        ariaControls.split(/\s+/).forEach( (id) => {
+          const panel = document.getElementById(id)
+          if (panel) {
+            tabPanels.push(panel)
+          }
+          else {
+            this.logger.warn("Tab %o references panel with id %s, but no such element exists with that id",tab,id)
+          }
+        })
+      }
+      if (tab == selectedTab) {
+        tab.setAttribute("aria-selected",true)
+        tab.setAttribute("tabindex","0")
+        tabPanels.forEach( (panel) => panel.removeAttribute("hidden") )
+        if (this.#pushAndRestoreTabState && !skipPushState)  {
+          let href = tab.getAttribute("href") || ""
+          if (href.startsWith("?")) {
+            let hrefQueryString = href.slice(1)
+            const anchorIndex = hrefQueryString.indexOf("#")
+            if (anchorIndex != -1) {
+              hrefQueryString = hrefQueryString.slice(-1 * (hrefQueryString.length - anchorIndex - 1))
+            }
+            const currentQuery = new URLSearchParams(window.location.search)
+            const hrefQuery    = new URLSearchParams(hrefQueryString)
+            hrefQuery.forEach( (value,key) => {
+              currentQuery.set(key,value)
+            })
+            href = "?" + currentQuery.toString() + (anchorIndex == -1 ? "" : hrefQueryString.slice(anchorIndex))
+          }
+          window.history.pushState({ tabId: tab.id },"",href)
+          window.addEventListener("popstate", this.#reloadTab)
+        }
+        this.dispatchEvent(new CustomEvent("brut:tabselected", { tabId: tab.id }))
+      }
+      else {
+        tab.setAttribute("aria-selected",false)
+        tab.setAttribute("tabindex","-1")
+        tabPanels.forEach( (panel) => panel.setAttribute("hidden", true) )
+      }
+    })
+  }
+
+
+  #tabs() {
+    const tabs = []
+    this.querySelectorAll("[role=tab]").forEach( (tab) => {
+      if ( (tab.tagName.toLowerCase() == "a") || (tab.tagName.toLowerCase() == "button") ) {
+        tabs.push(tab)
+      }
+      else {
+        this.logger.warn("An element with tag %s was assigned role=tab, and %s doesn't work that way. Use an <a> or a <button>",tab.tagName,this.constructor.name)
+      }
+    })
+    return tabs
+  }
+
+}
+export default Tabs

data/brut-js/src/Tracing.js

@@ -0,0 +1,247 @@
+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
+ *
+ * @customElement brut-tracing
+ */
+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

data/brut-js/src/appForTestingOnly.js

@@ -0,0 +1,15 @@
+import * as BrutJS from "./index.js"
+document.addEventListener("DOMContentLoaded", () => {
+  BrutJS.BrutCustomElements.define()
+  if (!HTMLDialogElement.prototype.showModal) {
+    HTMLDialogElement.prototype.showModal = function() {
+      this.open = true
+    }
+  }
+  if (!HTMLDialogElement.prototype.close) {
+    HTMLDialogElement.prototype.close = function(returnValue) {
+      this.open = false
+      this.returnValue = returnValue
+    }
+  }
+})

data/brut-js/src/index.js

@@ -0,0 +1,130 @@
+import BaseCustomElement           from "./BaseCustomElement"
+import AjaxSubmit                  from "./AjaxSubmit"
+import Autosubmit                  from "./Autosubmit"
+import ConfirmSubmit               from "./ConfirmSubmit"
+import ConfirmationDialog          from "./ConfirmationDialog"
+import ConstraintViolationMessage  from "./ConstraintViolationMessage"
+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 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
+ * be waited-on to properly assert behavior.
+ *
+ * @callback testCodeCallback
+ *
+ * @param {Object} objects - objects passed into your test that you may need.
+ * @param {Window} objects.window - Access to the top-level window object. Note that this provided by JSDOM and is not exactly like the `Window` you'd get in your browser.
+ * @param {Document} objects.document - Access to the top-level document object. Note that this provided by JSDOM and is not exactly like the `Document` you'd get in your browser.
+ * @param {Object} objects.assert - The NodeJS assert object that you should use to assert behavior.
+ * @param {Object} objects.fetchRequests - An array of `Request` instances given to `fetch`.  This will be updated as `fetch` is
+ * called and can be useful to assert the contents of what was requested via `fetch`.
+ *
+ * @example
+ * test("some test", ({document,assert}) => {
+ *   const element = document.querySelector("div")
+ *   assert(div.getAttribute("data-foo") != null)
+ * })
+ *
+ * @example
+ * test("some other test", ({document,window,assert}) => {
+ *   const element = document.querySelector("div")
+ *   assert.equal(window.history.state["foo"], "bar")
+ * })
+ */
+
+/**
+ * @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}
+ */
+/**
+ * @external fetch
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch|fetch}
+ */
+
+/**
+ * @external ValidityState
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/ValidityState|ValidityState}
+ */
+
+/**
+ * The standard `CustomElementRegistry`
+ *
+ * @external CustomElementRegistry
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry|CustomElementRegistry}
+ */
+
+/**
+ * @external Window
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/|Window}
+ */
+
+/** 
+ * @method confirm
+ * @memberof external:Window#
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm|confirm}
+ */
+
+/**
+ * Class that can be used to automatically define all of brut's custom
+ * elements.
+ */
+class BrutCustomElements {
+  static elementClasses = []
+  static define() {
+    this.elementClasses.forEach( (e) => {
+      e.define() 
+    })
+  }
+  static addElementClasses(...classes) {
+    this.elementClasses.push(...classes)
+  }
+}
+
+BrutCustomElements.addElementClasses(
+  // Ordering is important here - TBD how to make sure these are created in order
+  I18nTranslation,
+  CopyToClipboard,
+  Message,
+  ConfirmSubmit,
+  ConfirmationDialog,
+  ConstraintViolationMessages,
+  Form,
+  AjaxSubmit,
+  ConstraintViolationMessage,
+  Tabs,
+  LocaleDetection,
+  Autosubmit,
+  Tracing,
+)
+
+export {
+  AjaxSubmit,
+  Autosubmit,
+  BaseCustomElement,
+  BrutCustomElements,
+  ConfirmSubmit,
+  ConfirmationDialog,
+  ConstraintViolationMessage,
+  ConstraintViolationMessages,
+  Form,
+  I18nTranslation,
+  LocaleDetection,
+  Message,
+  RichString,
+  Tabs,
+  Tracing
+}
+