brut 0.16.0 → 0.18.0

data/brut-js/src/RichString.js

@@ -1,116 +0,0 @@
-/** 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, {allowBlank=false} = {}) {
-    if (possiblyDefinedStringOrRichString instanceof RichString) {
-      return possiblyDefinedStringOrRichString
-    }
-    if (allowBlank && possiblyDefinedStringOrRichString === "") {
-      return new RichString("")
-    }
-    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

@@ -1,168 +0,0 @@
-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/Toast.js

@@ -1,102 +0,0 @@
-import { BaseCustomElement, RichString, Message } from "brut-js"
-
-/**
- * Support for a toast component, which is a momentary message shown to the user, for example
- * if an aynchronous update has occured.
- *
- * To use this element, you should set up your CSS so that the element is hidden if there is no `key`
- * attribute set.  When the `key` attribute *is* set, the element should be shown.  You can use CSS animations
- * for this as needed, but the main thing to remember is that, without a `key` attribute, this element
- * should not be visible.
- *
- * The `key` attribute is expected to be an i18n key that references a `<brut-i18n-message>` on
- * the page, which contains the actual message to show the visitor.  When the `key` attribute is
- * set, this component will find an `<output>` inside itself, and replace the entire contents
- * with a `<brut-message>` component, using the same `key`.  This will cause the `<brut-message>`
- * to look up the key and put that text into the element.
- *
- * In addition to this lookup, this element will set appropriate ARIA attributes on the
- * created `<brut-message>` element.
- *
- * Further, if there is a `<button>` inside this element, it will be used to close the toast by removing the
- * `key` attribute (which, assuming your CSS is correct, will hide the element).
- *
- * @property {string} key - an I18n key of the message to show in the toast.  When you generate
- *                          the toast's HTML on the server, do not set key.  Then, when you need
- *                          to display the toast, use JavaScript to set the key. This will
- *                          trigger its behavior as described above.
- *
- * @example
- * <style>
- *   brut-toast {
- *     display: none;
- *   }
- *   brut-toast[key] {
- *     display: block;
- *   }
- * </style>
- * <brut-i18n-translation key="toast.saved">Save successful</brut-i18n-translation>
- * <brut-toast>
- *   <div>
- *   <output></output>
- *   <button>Close</button>
- *   </div>
- * </brut-toast>
- * <!-- now, if you set the key to "toast.saved", the HTML will be changed as follows: -->
- * <brut-toast key="toast.saved">
- *   <div>
- *   <output>
- *     <brut-message key="toast.saved" role="status" aria-live="polite" aria-atomic="true">
- *       Save successful
- *     </brut-message>
- *   </output>
- *   <button>Close</button>
- *   </div>
- * </brut-toast>
- */
-class Toast extends BaseCustomElement {
-  static tagName = "brut-toast"
-
-  static observedAttributes = [
-    "show-warnings",
-    "key",
-  ]
-
-  #key = null
-  #closeListener = (event) => {
-    event.preventDefault()
-    this.removeAttribute("key")
-  }
-
-  keyChangedCallback({newValue}) {
-    this.#key = RichString.fromString(newValue)
-  }
-
-  update() {
-    const closeButton = this.querySelector("button")
-
-    if (closeButton) {
-      closeButton.addEventListener("click", this.#closeListener)
-    }
-
-    if (!this.#key) {
-      return
-    }
-    const output = this.querySelector("output")
-    if (!output) {
-      this.logger.warn("No <output> element found, so toast will not be displayed")
-      return
-    }
-    const messageNode = Message.createElement(document,{
-      "key": this.#key,
-      "role": "status",
-      "aria-live": "polite",
-      "aria-atomic": "true"
-    })
-    output.replaceChildren(messageNode)
-    this.style.animation = "none"
-    this.offsetWidth // Trigger reflow to restart the animation
-    this.style.animation = ""
-  }
-}
-export default Toast

data/brut-js/src/Tracing.js

@@ -1,247 +0,0 @@
-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

@@ -1,15 +0,0 @@
-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
-    }
-  }
-})