brut-js 0.0.1

package/src/ConstraintViolationMessages.js

@@ -0,0 +1,90 @@
+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-constraint-violation-message>` elements
+ * as children, where the key represents the particular errors present in the `ValidityState` passed
+ * to `createMessages`.
+ *
+ * @property {boolean} server-side if true, this indicates the element contains constraint violation messages
+ *                                 from the server.  Currently doesn't affect this element's behavior, however
+ *                                 AjaxSubmit will use it to locate where it should insert server-side errors.
+ * @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
+ */
+class ConstraintViolationMessages extends BaseCustomElement {
+  static tagName = "brut-constraint-violation-messages"
+
+  static observedAttributes = [
+    "show-warnings",
+    "server-side",
+    "input-name",
+  ]
+
+
+  serverSideChangedCallback({newValueAsBoolean}) {
+    // attribute listed for documentation purposes only
+  }
+  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-constraint-violation-message>` would be created with `key="general.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.clearMessages()
+    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 all messages. Useful for when an input has become valid during a session.
+   */
+  clearMessages() {
+    this.textContent = ""
+  }
+
+  #VALIDITY_STATE_ATTRIBUTES = [
+    "badInput",
+    "customError",
+    "patternMismatch",
+    "rangeOverflow",
+    "rangeUnderflow",
+    "stepMismatch",
+    "tooLong",
+    "tooShort",
+    "typeMismatch",
+    "valueMissing",
+  ]
+}
+export default ConstraintViolationMessages

package/src/Form.js

@@ -0,0 +1,117 @@
+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:
+ *
+ * * Using the `:invalid` pseudo selector isn't great, because freshly rendered forms
+ *   that have `required` elements will match the `:invalid` selector. You really want
+ *   to only show errors if the user has tried to submit the form.  Thus, the `FORM` inside
+ *   this custom element will be given the attribute `data-submitted` if a submission
+ *   has been attempted.  This allows you to target your CSS at invalid inputs
+ *   only when submission has occured.
+ * * 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-constraint-violation-messages` 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-constraint-violation-messages>
+ *       </brut-constraint-violation-messages>
+ *     </label>
+ *     <div> <!-- container need not be a label -->
+ *       <input type="text" required minlength="4" name="alias">
+ *       <brut-constraint-violation-messages>
+ *       </brut-constraint-violation-messages>
+ *     </div>
+ *   </form>
+ * </brut-form>
+ *
+ * @see ConstraintViolationMessages
+ */
+class Form extends BaseCustomElement {
+  static tagName = "brut-form"
+  static observedAttributes = [
+    "show-warnings",
+  ]
+
+  #markFormSubmitted = (event) => {
+    const form = event.target.form
+    if (!form) {
+      this.logger.warn("%o had no form",event.target)
+      return
+    }
+    form.dataset["submitted"] = true
+  }
+  #updateValidity = (event) => {
+    this.#updateErrorMessages(event)
+  }
+  #sendValid = () => {
+    this.dispatchEvent(new CustomEvent("brut:valid"))
+  }
+  #sendInvalid = () => {
+    this.dispatchEvent(new CustomEvent("brut:invalid"))
+  }
+
+  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.#markFormSubmitted)
+        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}:not([server-side])`
+    const errorLabels = element.parentNode.querySelectorAll(selector)
+    if (errorLabels.length == 0) {
+      this.logger.warn(`Did not find any elements matching ${selector}, so no error messages will be shown`)
+      return
+    }
+    let anyErrors = false
+    errorLabels.forEach( (errorLabel) => {
+      if (element.validity.valid) {
+        errorLabel.clearMessages()
+      }
+      else {
+        anyErrors = true
+        errorLabel.createMessages({
+          validityState: element.validity,
+          inputName: element.name
+        })
+      }
+    })
+    if (anyErrors) {
+      this.#sendInvalid()
+    }
+    else {
+      this.#sendValid()
+    }
+  }
+}
+export default Form

package/src/I18nTranslation.js

@@ -0,0 +1,59 @@
+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>
+ */
+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

package/src/LocaleDetection.js

@@ -0,0 +1,93 @@
+import BaseCustomElement from "./BaseCustomElement"
+
+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

package/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

package/src/Message.js

@@ -0,0 +1,55 @@
+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
+ */
+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

package/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