brut 0.0.20 → 0.0.22

data/brut-js/src/BaseCustomElement.js

@@ -0,0 +1,261 @@
+import Logger from "./Logger"
+import RichString from "./RichString"
+
+/** Base class for Custom Elements that provides a few quality-of-life enhancements.
+  * 
+  * Custom elements that use this base class instead of `HTMLElement` get the following features:
+  *
+  * * `connectedCallback` and `attributeChangedCallback` call into a central `update` method where the 
+  *   class can centralilize its logic
+  * * Instead of implementing `attributeChangedCallback` and checking the name, per-attribute
+  *   callbacks can be implemented that are called when an observed attribute is changed.  See {@link
+  *   attributeChangedCallback}.
+  * * Support for defining the element by declaring a tag name
+  * * Opt-in debugging support to allow verbose logging of mistaken use of the element that can be turned
+  *   off for production use.
+  *
+  * How to use this class:
+  *
+  * 1. Your custom element should extend this class via `extends BaseCustomElement`
+  * 2. Create a static property called `tagName` that will be your element's tag name. Remember that all tag names must have a dash in them.
+  * 3. Create a static property called `observedAttributes` that is an array of attribute names your element supports. This is part of the HTML spec and not specific to this base class.
+  * 4. If you include the attribute `show-warnings` in your list of `observedAttributes`, you will have enhanced debugging abilities.
+  * 5. For each attribute *other* than `show-warnings`, implement a callback to receive notifications on the attribute's changes. See {@link attributeChangedCallback} for more info.
+  * 6. Implement `update` to execute whatever logic the component needs.  `update` will be called multiple times and thus should be relatively idempotent.  Specifically, it will be called after any attribute has changed, and it will be called as part of the standard `connectedCallback`.
+  * 7. To use your component, call the static {@link define} method.
+  *
+  * Debugging
+  *
+  * Custom Elements have to work under a variety of degenerate cirucmstances.  Further, if you are building 
+  * elements that wrap and enhance conventional elements, it can be easy to make a mistake, for example intending
+  * to wrap a `FORM`, but wrapping only an `INPUT`.
+  *
+  * To help debug these situations, you are encouraged to use `this.logger.warn(...)` to emit warnings when
+  * potentially incorrect use of your component is detected.  By default, these warnings will not be shown. This
+  * provides your users with a drama-free console.  During development, however, you can add the `show-warnings`
+  * attribute to your element.  If that is set, warnings *are* shown in the console.
+  *
+  * `show-warnings` can be given a value, in which case that value if used to prefix all warnings the element emits.
+  * This can be useful to know which use of an element is causing problems.  If you don't give any value
+  * to `show-warnings`, the element's `id` will be used as the prefix.  If the element has no `id`, you will
+  * still see warnings, but without a prefix. This could make it hard to know where the warnings are coming from.
+  *
+  * @example
+  * // Replaces all span elements inside the component with
+  * // an upper-cased value of the attribute 'some-attribute'
+  * class MyComponent extends BaseCustomElement {
+  *   static tagName = "my-component"
+  *   static observedAttributes = [
+  *     "show-warnings",
+  *     "some-attribute",
+  *   ]
+  *
+  *   someAttributeChangedCallback({newValue}) {
+  *     this.someAttribute = newValue ? newValue.toUpperCase() : null
+  *   }
+  *
+  *   update() {
+  *     const spans = this.querySelectorAll("span")
+  *     if (spans.length == 0) {
+  *       this.logger.warn("Did not find any <span> elements - element won't do anything")
+  *     }
+  *     spans.forEach( (element) => {
+  *       element.textContent = this.someAttribute
+  *     })
+  *   }
+  * }
+  * docment.addEventListener("DOMContentLoaded", () => {
+  *   MyComponent.define()
+  * })
+  *
+  * // Then, in your HTML
+  * <my-component some-attribute="hello there">
+  *   <span></span>
+  *   <div></div>
+  *   <span></span>
+  * </my-component>
+  *
+  * // The browser will effectively produce this HTML:
+  * <my-component some-attribute="hello there">
+  *   <span>HELLO THERE</span>
+  *   <div></div>
+  *   <span>HELLO THERE</span>
+  * </my-component>
+  *
+  * // If JavaScript (or browser dev tools) changed some-attribute
+  * // to be "goodbye then", the markup will change to look like so:
+  * <my-component some-attribute="goodby then">
+  *   <span>GOODBYE THEN</span>
+  *   <div></div>
+  *   <span>GOODBYE THEN</span>
+  * </my-component>
+  */
+class BaseCustomElement extends HTMLElement {
+
+  /** A {@link Logger} you can use to write warning messages.  By default, these
+   * messages are not shown in the console. If you put `show-warnings` as an attribute on your
+   * element, warnings sent to this logger *are* shown.
+   */
+  logger = Logger.forPrefix(null)
+
+  #_connectedCallbackCalled    = false
+  #_disconnectedCallbackCalled = false
+
+  constructor() {
+    super()
+    this.logger = Logger.forPrefix(null)
+  }
+
+  /** You must call this to define the custom element.  This is bascially
+   * a wrapper around `customElements.define`. It is recommended that you call 
+   * this inside a `DOMContentLoaded` event, or after the page's HTML has been processed.
+   * 
+   * @see external:CustomElementRegistry
+   */
+  static define() {
+    if (!this.tagName) {
+      throw `To use BaseCustomElement, you must define the static member tagName to return your custom tag's name`
+    }
+    customElements.define(this.tagName, this)
+  }
+
+  showWarningsChangedCallback({oldValue,newValue}) {
+    let oldLogger
+    if (!oldValue && newValue) {
+      oldLogger = this.logger
+    }
+    let prefix = newValue == "" ? this.id : newValue
+    if (!prefix) {
+      prefix = "UNKNOWN COMPONENT"
+    }
+    this.logger = Logger.forPrefix(prefix)
+    if (oldLogger) {
+      this.logger.dump(oldLogger)
+    }
+  }
+
+  /**
+   * Overrides the standard callback to allow subclasses to have a slightly easier API when responding
+   * to attribute changes. You can override this to use the custom element callback directly. Note that if
+   * you do, `show-warnings` will not have any affect and you probably don't need to bother using
+   * this class as your base class.
+   *
+   * This method will locate a per-attribute method and call that.
+   * Attribute names are assumed to be in kebab-case and are translated to camelCase to create a method name.
+   * That method is `«attributeInCamelCase»ChangedCallback`, so if your attribute is `hex-code`,
+   * a method named `hexCodeChangedCallback` in invoked.  If no such method is defined, a
+   * warning is logged in the console, regardless of the `show-warnings` attribute.
+   *
+   * The method is invoked with `{oldValue,newValue,newValueAsBoolean}` - i.e. an object and not positional parameters. This 
+   * means your implementation can omit any parameters it doesn't care about. `newValueAsBoolean` is not part of
+   * the custom element spec, but is provided as an unambiguous way to know if a boolean attribute was set or not. This is
+   * because if the value is set, it is likely to be the empty string, which is considered false by JavaScript. Cool.
+   *
+   * The return value of the method is ignored.
+   *
+   * After your method is called, if there is a method named `update`, it is called with no arguments.
+   *
+   * What this allows you to do is separate how you manage your element's attributes from how your logic
+   * is managed. For complex elements that take a lot of attributes, this can simplify your element's code without straying too far from the spec.
+   *
+   * @example
+   *
+   * // If your element accepts the attribute `warning-message` that will be trimmed of whitespace
+   * // then placed into all `H1` tags inside the element, you can manage that like so:
+   * class MyElement extends BaseCustomElement {
+   *   static tagName = "my-element"
+   *   static observedAttributes = [
+   *     "warning-message",
+   *   ]
+   *
+   *   // called by attributeChangedCallback when warning-message's value changes
+   *   warningMessageChangedCallback({newValue}) {
+   *     this.warningMessage = (newValue || "").trim()
+   *   }
+   *
+   *   // called after attributeChangedCallback calls warningMessageChangedCallback
+   *   update() {
+   *     this.querySelectorAll("h1").forEach( (e) => e.textContent = this.warningMessage )
+   *   }
+   * }
+   *
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements}
+   *
+   */
+  attributeChangedCallback(name,oldValue,newValue) {
+    const callbackName = `${new RichString(name).camelize()}ChangedCallback`
+    if (this[callbackName]) {
+      const newValueAsBoolean = newValue !== null
+      this[callbackName]({oldValue,newValue,newValueAsBoolean})
+    }
+    else if (this.constructor.observedAttributes.indexOf(name) != -1) {
+      console.warn("Observing %s but no method named %s was found to handle it",name,callbackName)
+    }
+    this.__update()
+  }
+  
+  /** Overrides the custom element callback to set internal flags allowing you to know if your
+   * element has been disconnected. When an element is disconnected, `update` is not called.
+   *
+   * If you want to add your own logic during disconnection, override {@link onDisconnected}.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements}
+   */
+  disconnectedCallback() {
+    this.#_disconnectedCallbackCalled = true
+    this.onDisconnected()
+  }
+
+  /** Override this to add logic when `disconnectedCallback` is called by the browser.  This will
+   * not be called if you overrode `disconnectedCallback`.
+   */
+  onDisconnected() {}
+
+  /** Overrides the custom element callback to set internal flags allowing you to know if your
+   * element has been connected. `update` is still called for elements that have not yet connected, however
+   * in practice your element will be connected before any codepath that calls `update` is called.
+   *
+   * To add logic when your element is connected, override {@link onConnected}
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements}
+   * @see BaseCustomElement#connectedCallbackCalled
+   */
+  connectedCallback() {
+    this.#_connectedCallbackCalled = true
+    this.onConnected()
+    this.__update()
+  }
+
+  /** Override this to add logic when `connectedCallback` is called by the browser. This will
+   * not be called if you overrode `connectedCallback`
+   */
+  onConnected() {}
+
+  /** Returns true if this element is connected and the connected callback has been called.
+   * This is different from `Node#isConnected`, which can return true before `connectedCallback` is called.
+   */
+  get connectedCallbackCalled() { return !!this.#_connectedCallbackCalled }
+
+  /** Override this to perform whatever logic your element must perform.
+   * Because changes to your element's attributes can happen at any time and in any order,
+   * you will want to consolidate all logic into one method—this one. You will also
+   * want to make sure that this method is idempotent and fault-tolerant. It will be called multiple times.
+   *
+   * It is called by {@link BaseCustomElement#attributeChangedCallback|attributeChangedCallback} and {@link BaseCustomElement#connectedCallback|connectedCallback}, however
+   * it will *not* be called after the elment has been disconnected.
+   *
+   * That means that any event listeners, rendering, content manipulation, or other behavior should happen hear
+   * and it *must* be idempotent.  In particular, any event listeners you attach must be done with care. Using
+   * anonymous functions could result in duplicate listeners.
+   */
+  update() {}
+
+  __update() {
+    if (this.#_disconnectedCallbackCalled) {
+      return
+    }
+    this.update()
+  }
+}
+export default BaseCustomElement

data/brut-js/src/ConfirmSubmit.js

@@ -0,0 +1,116 @@
+import BaseCustomElement from "./BaseCustomElement"
+import RichString from "./RichString"
+import ConfirmationDialog from "./ConfirmationDialog"
+
+/** Confirms form submissions with the user before allowing the form to be submitted. This can be applied per submit
+ * button and only affects the behavior of `button` or `input type=submit`, and *only* if no other click handler
+ * has been put onto those buttons.  Note that this does not affect links (`a` elements).
+ *
+ * This can ask for confirmation with {@link external:Window#confirm} or a
+ * `brut-confirmation-dialog`. What it will use depends on several factors, all of which
+ * are geared toward doing the right thing. Note that setting `show-warnings` will elucidate the reasons
+ * this component does what it does.
+ *
+ * * If `dialog` is set:
+ *   - If that id is on a `<brut-confirmation-dialog>` that is used.
+ *   - If not, `window.confirm` is used.
+ * * If `dialog` is not set:
+ *   - If there is exactly one `<brut-confirmation-dialog>` on the page, this is used.
+ *   - If there is more than one, or no `<brut-confirmation-dialog>`s, `window.confirm` is used.
+ *
+ * @see ConfirmationDialog
+ *
+ * @property {string} message - the message to show that asks for confirmation. It should be written such that
+ *                              "OK" is grammatically correct for confirmation and "Cancel" is for aborting.
+ * @property {string} dialog - optional ID of the `brut-confirmation-dialog` to use instead of `window.confirm`.
+ *                             If there is no such dialog or the id references the wrong element type,
+ *                             `window.confirm` will be used.  Setting `show-warnings` will generate a warning for this.
+ *
+ * @customElement brut-confirm-submit
+ */
+class ConfirmSubmit extends BaseCustomElement {
+  static tagName = "brut-confirm-submit"
+
+  static observedAttributes = [
+    "message",
+    "dialog",
+    "show-warnings",
+  ]
+
+  #message      = new RichString("")
+  #confirming   = false
+  #dialogId     = null
+
+  messageChangedCallback({newValue}) {
+    this.#message = new RichString(newValue || "")
+  }
+
+  dialogChangedCallback({newValue}) {
+    this.#dialogId = RichString.fromString(newValue)
+  }
+
+  constructor() {
+    super()
+    this.onClick = (event) => {
+      if (this.#confirming) {
+        this.#confirming = false
+        return
+      }
+      if (this.#message.isBlank()) {
+        this.logger.warn("No message provided, so cannot confirm")
+        return
+      }
+      const dialog = this.#findDialog()
+      if (dialog) {
+        event.preventDefault()
+        dialog.setAttribute("message",this.#message.toString())
+        const buttonLabel = event.target.getAttribute("aria-label") || event.target.textContent
+        dialog.setAttribute("confirm-label",buttonLabel)
+        this.#confirming = true
+        dialog.showModal((confirm) => {
+          if (confirm) {
+            event.target.click()
+          }
+          else {
+            this.#confirming = false
+          }
+        })
+      }
+      else {
+        const result = window.confirm(this.#message)
+        if (!result) {
+          event.preventDefault()
+        }
+      }
+    }
+  }
+
+  #findDialog() {
+    if (this.#dialogId) {
+      const dialog = document.getElementById(this.#dialogId)
+      if (dialog) {
+        if (dialog.tagName.toLowerCase() != ConfirmationDialog.tagName) {
+          throw `${this.#dialogId} is the id of a '${dialog.tagName}', not '${ConfirmationDialog.tagName}'`
+        }
+        return dialog
+      }
+      this.logger.warn(`No dialog with id ${this.#dialogId} - using window.confirm as a fallback`)
+      return null
+    }
+    const dialogs = document.querySelectorAll(ConfirmationDialog.tagName)
+    if (dialogs.length == 1) {
+      return dialogs[0]
+    }
+    if (dialogs.length == 0) {
+      this.logger.warn(`No '${ConfirmationDialog.tagName}' found in document - using window.confirm as a fallback`)
+      return null
+    }
+    throw `Found ${dialogs.length} '${ConfirmationDialog.tagName}' elements. Not sure which to use. Remove all but one or specify the 'dialog' attribute on this element to specify which one to use`
+  }
+
+  update() {
+    this.querySelectorAll("button").forEach( (button) => button.addEventListener("click", this.onClick) )
+    this.querySelectorAll("input[type=submit]").forEach( (button) => button.addEventListener("click", this.onClick) )
+  }
+}
+export default ConfirmSubmit

data/brut-js/src/ConfirmationDialog.js

@@ -0,0 +1,143 @@
+import BaseCustomElement from "./BaseCustomElement"
+import RichString from "./RichString"
+
+/**
+ * Enhances a `DIALOG` element to allow it to be used for confirmation. Mostly useful
+ * with {@link Confirm}.
+ *
+ * This element must:
+ *
+ * * Wrap a `<DIALOG>` element
+ * * Contain an `<H1>` where the message will go
+ * * Have a `<BUTTON>` with value `ok` that will be considered the confirmation button.
+ * * Have a `<BUTTON>` with value `cancel` that will be considered the denial button.
+ *
+ * Omitting these will cause this element to not work properly. Set `show-warnings` to see
+ * warnings on this.
+ *
+ * @property {string} message - the message to use to ask for confirmation
+ * @property {string} confirm-label - the label to use for the "OK" or "Confirm" button
+ *
+ * @example <caption>Minimal Example</caption>
+ * <brut-confirmation-dialog message="This cannot be undone" confirm-label="DOIT">
+ *   <dialog>
+ *     <h1></h1>
+ *     <button value="ok"></button>
+ *     <button value="cancel">Nevermind</button>
+ *   </dialog>
+ * </brut-confirmation-dialog>
+ *
+ * @customElement brut-confirmation-dialog
+ */
+class ConfirmationDialog extends BaseCustomElement {
+  static tagName = "brut-confirmation-dialog"
+  static observedAttributes = [
+    "message",
+    "confirm-label",
+    "show-warnings"
+  ]
+
+  #onClose = () => {}
+  #message = new RichString("")
+  #confirmLabel = new RichString("OK")
+
+  constructor() {
+    super()
+    this.okListener = (event) => {
+      this.#closeDialog()
+      this.#onClose(true)
+    }
+    this.cancelListener = (event) => {
+      this.#closeDialog()
+      this.#onClose(false)
+    }
+  }
+
+  messageChangedCallback({newValue}) {
+    this.#message = RichString.fromString(newValue)
+  }
+
+  confirmLabelChangedCallback({newValue}) {
+    this.#confirmLabel = RichString.fromString(newValue)
+  }
+
+  /**
+   * Call this to show the dialog.  When the dialog is closed, `onClose` is called with the result.
+   *
+   * @param {function} onClose - a function called with either `true` or `false`, if the dialog was confirmed or 
+   * denied, respectively.
+   *
+   * @example
+   * dialog.showModal( (confirmed) => {
+   *   if (confirmed) {
+   *     form.submit()
+   *   }
+   *   else {
+   *     // do nothing
+   *   }
+   * })
+   */
+  showModal(onClose) {
+    const dialog = this.#dialog
+    if (dialog) {
+      this.#onClose = onClose || (() => {})
+      dialog.showModal()
+    }
+    else {
+      this.logger.warn("No <dialog> found to show")
+    }
+  }
+
+  get #dialog() {
+    return this.querySelector("dialog")
+  }
+
+  #closeDialog() {
+    const dialog = this.#dialog
+    if (dialog) {
+      dialog.close()
+    }
+  }
+
+  update() {
+    const dialog = this.#dialog
+    if (!dialog) {
+      this.logger.warn("Could not find a <dialog> - this custom element won't do anything")
+      return
+    }
+    this.#setMessage(dialog)
+    this.#setupButtons()
+  }
+
+  #setMessage(dialog) {
+    const h1 = dialog.querySelector("h1")
+    if (h1) {
+      if (this.#message.isBlank()) {
+        h1.textContent = null
+      }
+      else {
+        h1.textContent = this.#message.toString()
+      }
+    }
+    else {
+      this.logger.warn("Dialog had no <h1>, so nowhere to put the message")
+    }
+  }
+
+  #setupButtons() {
+    const okButton     = this.querySelector("button[value='ok']")
+    const cancelButton = this.querySelector("button[value='cancel']")
+
+    if (!okButton || !cancelButton) {
+      if (!okButton)     { this.logger.warn("no <button value='ok'> which is required for this dialog to work") }
+      if (!cancelButton) { this.logger.warn("no <button value='cancel'> which is required for this dialog to work") }
+      return
+    }
+
+    okButton.textContent = this.#confirmLabel
+
+    okButton.addEventListener("click"     , this.okListener)
+    cancelButton.addEventListener("click" , this.cancelListener)
+  }
+}
+export default ConfirmationDialog

data/brut-js/src/ConstraintViolationMessage.js

@@ -0,0 +1,125 @@
+import BaseCustomElement from "./BaseCustomElement"
+import RichString from "./RichString"
+import I18nTranslation from "./I18nTranslation"
+
+/** Like {@link Message} but specific to constraint violations of input fields.  This accepts the name
+ * of an input field via `input-name`, which can be used to locate the field's localized name.
+ *
+ * Here is how the field's name is determined:
+ *
+ * 1. It will look for a `<brut-i18n-translation>` element with the `key` `cv.fe.fieldNames.«input-name»`.
+ * 2. If that's not found, it will attempt to use "this field" by locating a `<brut-i18n-translation>` element with the `key`
+ *    `cv.this_field` (the underscore being what is used on Brut's server side).
+ * 3. If that is not found, it will use the literaly string "this field" and emit a console warning.
+ *
+ * @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.
+ * @property {string} input-name - the name of the input, used to insert into the message, e.g. "Title is required".
+ * @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.
+ *
+ * @see I18nTranslation
+ * @see ConstraintViolationMessages
+ * @see Message
+ *
+ * @customElement brut-cv
+ */
+class ConstraintViolationMessage extends BaseCustomElement {
+  static tagName = "brut-cv"
+
+  static observedAttributes = [
+    "show-warnings",
+    "key",
+    "input-name",
+    "server-side",
+  ]
+
+  static createElement(document,attributes) {
+    const element = document.createElement(ConstraintViolationMessage.tagName)
+    element.setAttribute("key",this.i18nKey("fe", attributes.key))
+    element.setAttribute("input-name",attributes["input-name"])
+    if (Object.hasOwn(attributes,"show-warnings")) {
+      element.setAttribute("show-warnings",attributes["show-warnings"])
+    }
+    return element
+  }
+
+  static markServerSide(element) {
+    if (element.tagName.toLowerCase() == this.tagName) {
+      element.setAttribute("server-side", true)
+    }
+  }
+
+  static clientSideSelector() {
+    return `${this.tagName}:not([server-side])`
+  }
+
+  static serverSideSelector() {
+    return `${this.tagName}[server-side]`
+  }
+
+  /** Returns the I18N key used for front-end constraint violations. This is useful
+   * if you need to construct a key and want to follow Brut's conventions on how they
+   * are managed.
+   *
+   * @param {...String} keyPath - parts of the path of the key after the namespace that Brut manages.
+   */
+  static i18nKey(...keyPath) {
+    const path = [ "cv" ]
+    return path.concat(keyPath).join(".")
+  }
+
+  #key          = null
+  #inputNameKey = null
+  #thisFieldKey = this.#i18nKey("this_field")
+
+  keyChangedCallback({newValue}) {
+    this.#key = newValue
+  }
+
+  inputNameChangedCallback({newValue}) {
+    this.#inputNameKey = this.#i18nKey("fe", "fieldNames", newValue)
+  }
+
+  serverSideChangedCallback({newValueAsBoolean}) {
+    // attribute listed for documentation purposes only
+  }
+
+  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
+    }
+
+    const fieldNameSelector = `${I18nTranslation.tagName}[key='${this.#inputNameKey}']`
+    const thisFieldSelector = `${I18nTranslation.tagName}[key='${this.#thisFieldKey}']`
+
+    let fieldNameTranslation = document.querySelector(fieldNameSelector)
+    if (!fieldNameTranslation) {
+      this.logger.info("Could not find translation for input/field name based on selector '%s'. Will try 'this field' fallback",fieldNameSelector)
+      fieldNameTranslation = document.querySelector(thisFieldSelector)
+      if (!fieldNameTranslation) {
+        this.logger.info("Could not find translation for 'this field' fallback key, based on selector '%s'",thisFieldSelector)
+      }
+    }
+
+    const fieldName = fieldNameTranslation ? fieldNameTranslation.translation() : "this field"
+    this.textContent = RichString.fromString(translation.translation({ field: fieldName })).capitalize().toString()
+  }
+
+  /** Helper that calls the static version */
+  #i18nKey(...keyPath) {
+    return this.constructor.i18nKey(...keyPath)
+  }
+
+
+}
+export default ConstraintViolationMessage