brut 0.17.0 → 0.18.0

data/brut-js/src/ConstraintViolationMessages.js

@@ -1,98 +0,0 @@
-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.cs.rangeUnderflow"`.
-   *
-   * The `cv.cs` 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

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

@@ -1,147 +0,0 @@
-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 you have generated a `<brut-cv-messages input-name="«input name»"></brut-cv-messasges>`, it will be populated with `<brut-cv>` elements for each client-side constraint violation, based on 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 input-name="username">
- *       </brut-cv-messages>
- *     </label>
- *     <div> <!-- container need not be a label -->
- *       <input type="text" required minlength="4" name="alias">
- *       <brut-cv-messages input-name="alias">
- *       </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 input-name="username">
- *         <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 input-name="alias">
- *         <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
-    let constraintViolationMessages = []
-    if (element.name && element.form) {
-      const selector = `${ConstraintViolationMessages.tagName}[input-name='${element.name}']`
-      constraintViolationMessages = element.form.querySelectorAll(selector)
-      if (constraintViolationMessages.length == 0) {
-        this.logger.warn(`Did not find any elements matching ${selector}, so no error messages will be shown`)
-      }
-    }
-    else {
-      if (element.name) {
-        this.logger.warn("Element has a name (%s), but is not associated with any form.", element.name)
-      }
-      else {
-        this.logger.warn("Element has a form, but has no name, which means we cannot locate %s by input-name", ConstraintViolationMessages.tagName)
-      }
-    }
-    if (constraintViolationMessages.length == 0) {
-      return
-    }
-    let anyErrors = false
-    constraintViolationMessages.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

@@ -1,64 +0,0 @@
-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) {
-    if (!this.#value) {
-      this.logger.warn("No value attribute for key '%s', so translation will be blank", this.#key)
-    }
-    return this.#value.replaceAll(/%\{([^}%]+)\}/g, (match,key) => {
-      if (interpolatedValues[key]) {
-        return interpolatedValues[key]
-      }
-      return match
-    })
-  }
-
-}
-export default I18nTranslation

data/brut-js/src/LocaleDetection.js

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

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

@@ -1,62 +0,0 @@
-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",
-  ]
-
-  /*
-   * Creates a new `<brut-message>` element with the given attributes.
-   */
-  static createElement(document,attributes) {
-    const element = document.createElement(Message.tagName)
-    Object.entries(attributes).forEach(([name,value]) => {
-      if (value !== null && value !== undefined) {
-        element.setAttribute(name,value)
-      }
-    })
-    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(), {allowBlank: true }).capitalize().toString()
-  }
-}
-
-export default Message