brut 0.0.21 → 0.0.23

data/brut-js/src/ConstraintViolationMessages.js

@@ -0,0 +1,98 @@
+import BaseCustomElement from "./BaseCustomElement"
+import RichString from "./RichString"
+import ConstraintViolationMessage from "./ConstraintViolationMessage"
+
+/**
+ * Custom element to translate keys from {@link external:ValidityState} into 
+ * actual messges for a human.  This works by inserting `<brut-cv>` elements
+ * as children, where the key represents the particular errors present in the `ValidityState` passed
+ * to `createMessages`. Note that this will not insert an element for `customError`, since there can't be
+ * any sort of general error message to correspond to that.
+ *
+ * @property {string} input-name if set, this indicates this element contains constraint violation messages
+ *                               for the input with this name inside the form this element is in. Currently doesn't affect
+ *                               this element's behavior, however AjaxSubmit will use it to locate where it 
+ *                               should insert server-side errors.
+ *
+ * @see Form
+ * @see ConstraintViolationMessage
+ * @see AjaxSubmit
+ *
+ * @customElement brut-cv-messages
+ */
+class ConstraintViolationMessages extends BaseCustomElement {
+  static tagName = "brut-cv-messages"
+
+  static observedAttributes = [
+    "show-warnings",
+    "input-name",
+  ]
+
+  inputNameChangedCallback({newValue}) {
+    // attribute listed for documentation purposes only
+  }
+
+  /** 
+   * Creates error messages based on the passed `ValidityState` and input name.
+   *
+   * This should be called as part of a Form validation event to provide a customized UX for
+   * the error messages, beyond what the browser would do by default.  The keys used are the same
+   * as the attributes of a `ValidityState`, so for example, a range underflow would mean that `validity.rangeUnderflow` would return
+   * true.  Thus, a `<brut-cv>` would be created with `key="cv.fe.rangeUnderflow"`.
+   *
+   * The `cv.fe` is hard-coded to be consistent with Brut's server-side translation management.
+   *
+   * @param {ValidityState} validityState - the return from an element's `validity` when it's found to have constraint violations.
+   * @param {String} inputName - the element's `name`.
+   */
+  createMessages({validityState,inputName}) {
+    const errors = this.#VALIDITY_STATE_ATTRIBUTES.filter( (attribute) => validityState[attribute] )
+    this.clearClientSideMessages()
+    errors.forEach( (key) => {
+      const options = {
+        key: key,
+        "input-name": inputName,
+      }
+      const showWarnings = this.getAttribute("show-warnings")
+      if (showWarnings != null) {
+        options["show-warnings"] = showWarnings
+      }
+      const element = ConstraintViolationMessage.createElement(document,options)
+      this.appendChild(element)
+    })
+  }
+
+  /**
+   * Clear any client-side messages previously inserted by another element.
+   * This is useful to remove potentially out-of-date messages to replace with up-to-date ones.
+   */
+  clearClientSideMessages() {
+    this.querySelectorAll(ConstraintViolationMessage.clientSideSelector()).forEach( (element) => {
+      this.removeChild(element)
+    })
+  }
+
+  /**
+   * Clear any server-side messages previously inserted by another element or rendered from the server.
+   * This is useful to remove potentially out-of-date messages to replace with up-to-date ones.
+   */
+  clearServerSideMessages() {
+    this.querySelectorAll(ConstraintViolationMessage.serverSideSelector()).forEach( (element) => {
+      this.removeChild(element)
+    })
+  }
+
+  #VALIDITY_STATE_ATTRIBUTES = [
+    "badInput",
+    "patternMismatch",
+    "rangeOverflow",
+    "rangeUnderflow",
+    "stepMismatch",
+    "tooLong",
+    "tooShort",
+    "typeMismatch",
+    "valueMissing",
+    // customError omitted, since it makes no sense as a general error key to look up
+  ]
+}
+export default ConstraintViolationMessages

data/brut-js/src/CopyToClipboard.js

@@ -0,0 +1,96 @@
+import BaseCustomElement from "./BaseCustomElement"
+
+/** Wraps a `<BUTTON>` that will copy text from another element into the system clipboard.  It will set various attributes on itself
+ * to allow styling the states of the process.
+ *
+ * Overall, the flow is as follows:
+ *
+ * 1. When the button is clicked, its default is prevented, and the element with the id of the `element` attribute is located.
+ * 2. If found, this element gets the `copying` attribute set.
+ * 3. If the copy completes successfully:
+ *    a. `copying` is removed
+ *    b. `copied` is set
+ *    c. `copied` is scheduled for removal in 2000ms or the number of milliseconds in the `copied-lifetime` attribute.
+ * 4. If the copy failed:
+ *    a. `copying` is removed
+ *    b. `errored` is set
+ *    c. The `brut:copyfailed` event is fired. It's detail contains a `text:` value with the text that was attempted to be copied.
+ *
+ * The intention is to use these attributes to style whatever UX you want.
+ *
+ * @property {string} element - ID of the element whose `textContent` is what will be copied to the clipboard.
+ * @property {number} copied-lifetime - number of milliseconds to wait before clearing the `copied` attribute after a successful copy.
+ * @property {boolean} copying - Set after a copy is initiated, but before it completes
+ * @property {boolean} copied - Set after a copy is completed successfully
+ * @property {boolean} errored - Set after a copy is fails
+ *
+ * @fires brut:copyfailed Fired when the copy fails to complete
+ *
+ * @example
+ * <pre><code id="code">dx/exec bin/setup</code></pre>
+ * <brut-copy-to-clipboard element="code">
+ *   <button>Copy</button>
+ * </brut-copy-to-clipboard>
+ *
+ * @customElement brut-copy-to-clipboard
+ */
+class CopyToClipboard extends BaseCustomElement {
+  static tagName = "brut-copy-to-clipboard"
+
+  static observedAttributes = [
+    "element",
+    "copied-lifetime",
+  ]
+
+  #elementId = null
+  #copiedLifetime = 2000
+
+  #copyCode = (event) => {
+    event.preventDefault()
+
+    const element = document.getElementById(this.#elementId)
+
+    if (!element) {
+      this.logger.info("No element with id %s, so nothing to copy",this.#elementId)
+      return
+    }
+    this.setAttribute("copying",true)
+
+    const text = element.textContent
+
+    navigator.clipboard.writeText(text).then( () => {
+      this.setAttribute("copied", true)
+    }).catch( (e) => {
+      this.setAttribute("errored", true)
+      this.dispatchEvent(new CustomEvent("brut:copyfailed", { detail: { text: text }}))
+    }).finally( () => {
+      this.removeAttribute("copying")
+      setTimeout( () => this.removeAttribute("copied"), 2000)
+    })
+  }
+
+  update() {
+    const button = this.querySelector("button")
+    if (button) {
+      button.addEventListener("click", this.#copyCode)
+    }
+    else {
+      this.logger.info("There is no button, so no way to initiate a copy")
+    }
+  }
+
+  elementChangedCallback({newValue}) {
+    this.#elementId = newValue
+  }
+
+  copiedLifetimeChangedCallback({newValue}) {
+    const newValueAsInt = parseInt(newValue)
+    if (!isNaN(newValueAsInt)) {
+      this.#copiedLifetime = newValueAsInt
+    }
+    else {
+      this.logger.info("Value '%s' for copied-lifetime is not a number. Ignoring it",newValue)
+    }
+  }
+}
+export default CopyToClipboard

data/brut-js/src/Form.js

@@ -0,0 +1,151 @@
+import BaseCustomElement from "./BaseCustomElement"
+import RichString from "./RichString"
+import AjaxSubmit from "./AjaxSubmit"
+import ConstraintViolationMessages from "./ConstraintViolationMessages"
+
+/** A web component that enhances a form it contains to make constraint validations
+ * easier to manage and 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
+ * when constraint violations have cleared.
+ *
+ * @example <caption>Basic Structure Required</caption>
+ * <brut-form>
+ *   <form ...>
+ *     <label>
+ *       <input type="text" required name="username">
+ *       <brut-cv-messages>
+ *       </brut-cv-messages>
+ *     </label>
+ *     <div> <!-- container need not be a label -->
+ *       <input type="text" required minlength="4" name="alias">
+ *       <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
+ *
+ * @customElement brut-form
+ */
+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)
+  }
+  #sendValid = () => {
+    this.dispatchEvent(new CustomEvent("brut:valid"))
+  }
+  #sendInvalid = () => {
+    this.dispatchEvent(new CustomEvent("brut:invalid"))
+  }
+
+  submittedInvalidChangedCallback() {}
+
+  update() {
+    const forms = this.querySelectorAll("form")
+    if (forms.length == 0) {
+      this.logger.warn("Didn't find any forms. Ignoring")
+      return
+    }
+    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) => {
+        ajaxSubmits.addEventListener("brut:submitok", this.#sendValid)
+        ajaxSubmits.addEventListener("brut:submitinvalid", this.#sendInvalid)
+      })
+    })
+  }
+
+  #updateErrorMessages(event) {
+    const element = event.target
+    const selector = ConstraintViolationMessages.tagName
+    let errorLabels = element.parentNode.querySelectorAll(selector)
+    if (errorLabels.length == 0) {
+      if (element.name && element.form) {
+        const moreGeneralSelector = `${ConstraintViolationMessages.tagName}[input-name='${element.name}']`
+        errorLabels = element.form.querySelectorAll(moreGeneralSelector)
+        if (errorLabels.length == 0) {
+          this.logger.warn(`Did not find any elements matching ${selector} or ${moreGeneralSelector}, so no error messages will be shown`)
+        }
+      }
+      else {
+        this.logger.warn("Did not find any elements matching %s and the form element has %s %s",
+          selector,
+          element.name ? "no name" : "a name, but",
+          element.form ? "no form" : "though has a form")
+      }
+    }
+    if (errorLabels.length == 0) {
+      return
+    }
+    let anyErrors = false
+    errorLabels.forEach( (errorLabel) => {
+      if (element.validity.valid) {
+        errorLabel.clearClientSideMessages()
+      }
+      else {
+        anyErrors = true
+        errorLabel.createMessages({
+          validityState: element.validity,
+          inputName: element.name
+        })
+      }
+    })
+    if (anyErrors) {
+      this.#sendInvalid()
+    }
+    else {
+      this.#sendValid()
+    }
+  }
+}
+export default Form

data/brut-js/src/I18nTranslation.js

@@ -0,0 +1,61 @@
+import BaseCustomElement from "./BaseCustomElement"
+
+/** Manages a translation based on a key and value, with the value potentially having interpolation.
+ *
+ * This is intended to be server-rendered with the subset of keys the server manages that are relevant
+ * to the front-end.  Any other code on the page can then locate an element with the desired key and
+ * call `translation` to get the human-readable key.  It is assumed that the server would render
+ * in the language required by the visitor, so there is no need to first select by locale.
+ *
+ * @property {string} key - an i18n key, presumably dot-delimited, however it can be any valid attribute value.
+ * @property {string} value - the value of the key, in the browser's locale. It may contain placeholders for interpolation using `%{«placeholder»}` syntax.
+ *
+ * @example
+ * <brut-i18n-translation key="greeting" value="Hello %{username}"></brut-i18n-translation>
+ *
+ * @customElement brut-i18n-translation
+ */
+class I18nTranslation extends BaseCustomElement {
+  static tagName = "brut-i18n-translation"
+
+  static observedAttributes = [
+    "show-warnings",
+    "key",
+    "value",
+  ]
+
+  #key = null
+  #value = ""
+
+  keyChangedCallback({newValue}) {
+    this.#key = newValue
+  }
+
+  valueChangedCallback({newValue}) {
+    this.#value = newValue ? String(newValue) : ""
+  }
+
+  /**
+   * Called by other JavaScript to get the translated string.
+   * @param {Object} interpolatedValues - Object where the keys are placeholders in the string for interpolation and the values are
+   * the values to replace.  Placeholders not in the translated value are ignored. Missing placeholders won't cause an error, but the
+   * placeholder will be present verbatim in the translated string.
+   *
+   * @example
+   * const element = document.querySeletor("brut-i18n-translation[key='greeting']")
+   * if (element) {
+   *   const translation = element.translation({ username: "Pat" })
+   *   alert(translation) // Shows 'Hello Pat'
+   * }
+   */
+  translation(interpolatedValues) {
+    return this.#value.replaceAll(/%\{([^}%]+)\}/g, (match,key) => {
+      if (interpolatedValues[key]) {
+        return interpolatedValues[key]
+      }
+      return match
+    })
+  }
+
+}
+export default I18nTranslation

data/brut-js/src/LocaleDetection.js

@@ -0,0 +1,117 @@
+import BaseCustomElement from "./BaseCustomElement"
+
+/**
+ * Send the locale and timezone from the browser to a configured endpoint on the server. This allows
+ * the server to have access to a reasonable guess as to the website visitor's locale/timezone.
+ *
+ * Note that this will not contact the server if both `locale-from-server` and `timezone-from-server` are
+ * set.  Further note that this will only contact the server once per page load, unless `url` is changed.
+ *
+ * @property {String} locale-from-server - omit this if the server doesn't know the visitor's locale. If both this and `timezone-from-server` are set, the server will not be contacted.
+ * @property {String} timezone-from-server - omit this if the server doesn't know the visitor's timezone. If both this and `locale-from-server` are set, the server will not be contacted.
+ * @property {URL} url - the url to send information to on the server.
+ * @property {number} timeout-before-ping-ms - MS to wait until this element contacts the server. A value of 0 will contact the server immediately. The default is 1,000, meaning this element will wait 1 second before contacting the server.
+ *
+ * @example <caption>When no information about the visitor is known</caption>
+ * <brut-locale-detection url="__brut/locale-detection"></brut-locale-detection>
+ *
+ * @example <caption>When all information about the visitor is known</caption>
+ * <brut-locale-detection
+ *   url="__brut/locale-detection"
+ *   locale-from-server="en-US"
+ *   timezone-from-server="America/New_York">
+ * </brut-locale-detection>
+ *
+ * @customElement brut-locale-detection
+ */
+class LocaleDetection extends BaseCustomElement {
+  static tagName = "brut-locale-detection"
+
+  static observedAttributes = [
+    "locale-from-server",
+    "timezone-from-server",
+    "url",
+    "timeout-before-ping-ms",
+    "show-warnings",
+  ]
+
+  #localeFromServer   = null
+  #timezoneFromServer = null
+  #reportingURL       = null
+  #timeoutBeforePing  = 1000
+  #serverContacted    = false
+
+  localeFromServerChangedCallback({newValue}) {
+    this.#localeFromServer = newValue
+  }
+
+  timezoneFromServerChangedCallback({newValue}) {
+    this.#timezoneFromServer = newValue
+  }
+
+  urlChangedCallback({newValue}) {
+    if (this.#serverContacted) {
+      this.#serverContacted = false
+    }
+    this.#reportingURL = newValue
+  }
+
+  timeoutBeforePingMsChangedCallback({newValue}) {
+    this.#timeoutBeforePing = newValue
+  }
+
+  update() {
+    if (this.#timeoutBeforePing == 0) {
+      this.#pingServerWithLocaleInfo()
+    }
+    else {
+      setTimeout(this.#pingServerWithLocaleInfo.bind(this), this.#timeoutBeforePing)
+    }
+  }
+
+  #pingServerWithLocaleInfo() {
+    if (!this.#reportingURL) {
+      this.logger.info("no url= set, so nowhere to report to")
+      return
+    }
+    if (this.#localeFromServer && this.#timezoneFromServer) {
+      this.logger.info("locale and timezone both set, not contacting server")
+      return
+    }
+
+    if (this.#serverContacted) {
+      this.logger.info("server has already been contacted at the given url, not doing it again")
+      return
+    }
+    this.#serverContacted = true
+
+    const formatOptions = Intl.DateTimeFormat().resolvedOptions()
+    const request = new Request(
+      this.#reportingURL,
+      {
+        headers: {
+          "Content-Type": "application/json",
+        },
+        method: "POST",
+        body: JSON.stringify({
+          locale: formatOptions.locale,
+          timeZone: formatOptions.timeZone,
+        }),
+      }
+    )
+
+    window.fetch(request).then( (response) => {
+      if (response.ok) {
+        this.logger.info("Server gave us the OK") 
+      }
+      else {
+        console.warn(response)
+      }
+    }).catch( (e) => {
+      console.warn(e)
+    })
+  }
+
+
+}
+export default LocaleDetection

data/brut-js/src/Logger.js

@@ -0,0 +1,90 @@
+/**
+ * Abstract interface for logging information from a component.
+ * This is intended to allow prefixed messages to be optionally shown
+ * in the console to help debug.
+ *
+ * @see BufferedLogger
+ * @see PrefixedLogger
+ * @see BaseCustomElement#logger
+ */
+class Logger {
+  /** Create a logger for the given prefix.
+   *
+   * @param {string|false} stringOrFalse - if false,returns a {@link BufferedLogger}. Otherwise, returns a {@link PrefixedLogger} using the param's value as the prefix.
+   *
+   * @returns {Logger}
+   */
+  static forPrefix(stringOrFalse) {
+    if (!stringOrFalse) {
+      return new BufferedLogger()
+    }
+    else {
+      return new PrefixedLogger(stringOrFalse)
+    }
+  }
+
+  /** Subclasses must implement this.
+   *
+   * @param {string} level - 'info' or 'warn' to indicate the logging level
+   * @param {...*} args - args to pass directly to console.log
+   */
+  log() {
+    throw `Subclass must implement`
+  }
+
+  /** Log an informational bit of information */
+  info(...args) { this.log("info",...args) }
+  /** Log a warning */
+  warn(...args) { this.log("warn",...args) }
+}
+
+/** Logger that buffers, but does not print, its logged messages.
+ * The reason it buffers them is to allow custom elements to retroatively log
+ * information captured before warnings were turned on.
+ */
+class BufferedLogger extends Logger {
+  constructor() {
+    super()
+    this.messages = []
+  }
+  log(...args) {
+    this.messages.push(args)
+  }
+}
+
+/** Log information to the JavaScript console.
+*/
+class PrefixedLogger extends Logger {
+  /** Create a PrefixedLogger.
+   *
+   * @param {string|true} prefixOrTrue - if true, uses the prefix `"debug"`, otherwise uses the param as the prefix to all
+   * messages output.
+   */
+  constructor(prefixOrTrue) {
+    super()
+    this.prefix = prefixOrTrue === true ? "debug" : prefixOrTrue
+  }
+
+  /** Dumps hte contents of a {@link BufferedLogger} to this logger's output.
+   *
+   * @param {BufferedLogger} bufferedLogger - a logger with pent-up messages, waiting to be logged.
+   */
+  dump(bufferedLogger) {
+    if (bufferedLogger instanceof BufferedLogger) {
+      bufferedLogger.messages.forEach( (args) => {
+        this.log(...args)
+      })
+    }
+  }
+
+  log(level,...args) {
+    if (typeof(args[0]) === "string") {
+      const message = `[prefix:${this.prefix}]:${args[0]}`
+      console[level](message,...(args.slice(1)))
+    }
+    else {
+      console[level](this.prefix,...args)
+    }
+  }
+}
+export default Logger

data/brut-js/src/Message.js

@@ -0,0 +1,56 @@
+import BaseCustomElement from "./BaseCustomElement"
+import RichString from "./RichString"
+import I18nTranslation from "./I18nTranslation"
+
+/** Renders a translated message for a given key, handling all the needed interpolation based
+ * on the existence of `<brut-i18n-translation>` elements on the page.
+ *
+ * When the `key` attribute has a value, this element will locate the `<brut-i18-translation>` element and call `translate`. Note that
+ * interpolation is not supported.
+ *
+ * @property {string} key - the i18n translation key to use.  It must map to the `key` of a `<brut-i18n-translation>` on the page or
+ * the element will not render any text.
+ *
+ * @see I18nTranslation
+ * @see ConstraintViolationMessage
+ *
+ * @customElement brut-message
+ */
+class Message extends BaseCustomElement {
+  static tagName = "brut-message"
+  static observedAttributes = [
+    "show-warnings",
+    "key",
+  ]
+
+  static createElement(document,attributes) {
+    const element = document.createElement(Message.tagName)
+    element.setAttribute("key",attributes.key)
+    element.setAttribute("show-warnings",attributes["show-warnings"])
+    return element
+  }
+
+  #key = null
+
+  keyChangedCallback({newValue}) {
+    this.#key = newValue
+  }
+
+  update() {
+    if (!this.#key) {
+      this.logger.info("No key attribute, so can't do anything")
+      return
+    }
+
+    const selector = `${I18nTranslation.tagName}[key='${this.#key}']`
+    const translation = document.querySelector(selector)
+    if (!translation) {
+      this.logger.info("Could not find translation based on selector '%s'",selector)
+      return
+    }
+
+    this.textContent = RichString.fromString(translation.translation()).capitalize().toString()
+  }
+}
+
+export default Message