brut-js 0.0.1

package/src/Tabs.js

@@ -0,0 +1,167 @@
+import BaseCustomElement from "./BaseCustomElement"
+
+/** Implements an in-page tab selector.  It's intended to wrap a set of `<a>` or `<button>` elements
+ * that represent the tabs of a tabbed UI, as defined by ARIA roles.  
+ *
+ * Each direct child must be an `<a>` or a `<button>`, though `<a>` is recommended.
+ * Any other elements are ignored.  Each `<a>` or `<button>`
+ * (herafter referred to as "tab") must have the correct ARIA attributes:
+ *
+ * * `role="tab"`
+ * * `aria-selected` as true or false, depending on what tab is selected when the page is first rendered.  This
+ *   custom element will ensure this value is updated as different tabs are selected.
+ * * `tabindex` should be 0 if selected, -1 otherwise. This custom element will ensure this value is updated as
+ *   different tabs are selected.
+ * * `aria-controls` to the ID or list of IDs of panels that should be shown when this tab is selected.
+ * * `id` to allow the `tab-panel` to refer back to this tab.
+ *
+ * This custom element will set click listeners on all tabs and, when clicked, hide all panels referred to by
+ * every tab (by setting the `hidden` attribute), then show only those panels referred to by the clicked
+ * tab.  You can use CSS to style everything the way you like it.
+ *
+ * @property {boolean} tab-selection-pushes-and-restores-state if set, this custom element will use the 
+ *                                                             history API to manage state. When a tab
+ *                                                             implemented by an `<a>` with an `href` is
+ *                                                             clicked, that `href` will be pushed into 
+ *                                                             the state.  When the back button is hit,
+ *                                                             this will select the previous tab as selected.
+ *                                                             Note that this will conflict with anything else
+ *                                                             on the page that manipulates state, so only
+ *                                                             set this if your UI is a "full page tab"
+ *                                                             style UI.
+ *
+ * @fires Tabs#brut:tabselected whenever the tab selection has changed
+ * @example
+ * <brut-tabs>
+ *   <a role="tab" aria-selected="true"  tabindex="0"  aria-controls="inbox-panel"  id="inbox-tab"
+ *      href="?tab=inbox">Inbox</a>
+ *   <a role="tab" aria-selected="false" tabindex="-1" aria-controls="drafts-panel" id="drafts-tab"
+ *      href="?tab=drafts">Drafts</a>
+ *   <a role="tab" aria-selected="false" tabindex="-1" aria-controls="spam-panel"   id="spam-tab"
+ *      href="?tab=spam">Spam</a>
+ * </brut-tabs>
+ * <section role="tabpanel" tabindex="0"  id="inbox-panel">
+ *   <h3>Inbox</h3>
+ * </section>
+ * <section role="tabpanel" tabindex="0" id="drafts-panel" hidden>
+ *   <h3>Drafts</h3>
+ * </section>
+ * <section role="tabpanel" tabindex="0" id="spam-panel"   hidden>
+ *   <h3>Spam</h3>
+ * </section>
+ * <!-- if a user clicks on 'Drafts', the DOM will be updated to look
+ *      effectively like so: -->
+ * <brut-tabs>
+ *   <a role="tab" aria-selected="false" tabindex="-1" aria-controls="inbox-panel"  id="inbox-tab"
+ *      href="?tab=inbox">Inbox</a>
+ *   <a role="tab" aria-selected="true"  tabindex="0"  aria-controls="drafts-panel" id="drafts-tab"
+ *      href="?tab=drafts">Drafts</a>
+ *   <a role="tab" aria-selected="false" tabindex="-1" aria-controls="spam-panel"   id="spam-tab"
+ *      href="?tab=spam">Spam</a>
+ * </brut-tabs>
+ * <section role="tabpanel" tabindex="0"  id="inbox-panel"  hidden>
+ *   <h3>Inbox</h3>
+ * </section>
+ * <section role="tabpanel" tabindex="-1" id="drafts-panel">
+ *   <h3>Drafts</h3>
+ * </section>
+ * <section role="tabpanel" tabindex="-1" id="spam-panel"   hidden>
+ *   <h3>Spam</h3>
+ * </section>
+ *
+ */
+class Tabs extends BaseCustomElement {
+  static tagName = "brut-tabs"
+  static observedAttributes = [
+    "tab-selection-pushes-and-restores-state",
+    "show-warnings",
+  ]
+
+  tabSelectionPushesAndRestoresStateChangedCallback({newValue,oldValue}) {
+    this.#pushAndRestoreTabState = newValue != null
+  }
+
+  update() {
+    this.#tabs().forEach( (tab) => {
+      tab.addEventListener("click", this.#tabClicked)
+    })
+  }
+
+  #pushAndRestoreTabState = false
+
+  #tabClicked = (event) => {
+    event.preventDefault()
+    this.#setTabAsSelected(event.target)
+    event.preventDefault()
+  }
+
+  #reloadTab = (event) => {
+    const tab = document.getElementById(event.state.tabId)
+    if (tab) {
+      this.#setTabAsSelected(tab, { skipPushState: true })
+    }
+  }
+
+  #setTabAsSelected(selectedTab, { skipPushState = false } = {}) {
+    this.#tabs().forEach( (tab) => {
+      const tabPanels = []
+      const ariaControls = tab.getAttribute("aria-controls")
+      if (ariaControls) {
+        ariaControls.split(/\s+/).forEach( (id) => {
+          const panel = document.getElementById(id)
+          if (panel) {
+            tabPanels.push(panel)
+          }
+          else {
+            this.logger.warn("Tab %o references panel with id %s, but no such element exists with that id",tab,id)
+          }
+        })
+      }
+      if (tab == selectedTab) {
+        tab.setAttribute("aria-selected",true)
+        tab.setAttribute("tabindex","0")
+        tabPanels.forEach( (panel) => panel.removeAttribute("hidden") )
+        if (this.#pushAndRestoreTabState && !skipPushState)  {
+          let href = tab.getAttribute("href") || ""
+          if (href.startsWith("?")) {
+            let hrefQueryString = href.slice(1)
+            const anchorIndex = hrefQueryString.indexOf("#")
+            if (anchorIndex != -1) {
+              hrefQueryString = hrefQueryString.slice(-1 * (hrefQueryString.length - anchorIndex - 1))
+            }
+            const currentQuery = new URLSearchParams(window.location.search)
+            const hrefQuery    = new URLSearchParams(hrefQueryString)
+            hrefQuery.forEach( (value,key) => {
+              currentQuery.set(key,value)
+            })
+            href = "?" + currentQuery.toString() + (anchorIndex == -1 ? "" : hrefQueryString.slice(anchorIndex))
+          }
+          window.history.pushState({ tabId: tab.id },"",href)
+          window.addEventListener("popstate", this.#reloadTab)
+        }
+        this.dispatchEvent(new CustomEvent("brut:tabselected", { tabId: tab.id }))
+      }
+      else {
+        tab.setAttribute("aria-selected",false)
+        tab.setAttribute("tabindex","-1")
+        tabPanels.forEach( (panel) => panel.setAttribute("hidden", true) )
+      }
+    })
+  }
+
+
+  #tabs() {
+    const tabs = []
+    this.querySelectorAll("[role=tab]").forEach( (tab) => {
+      if ( (tab.tagName.toLowerCase() == "a") || (tab.tagName.toLowerCase() == "button") ) {
+        tabs.push(tab)
+      }
+      else {
+        this.logger.warn("An element with tag %s was assigned role=tab, and %s doesn't work that way. Use an <a> or a <button>",tab.tagName,this.constructor.name)
+      }
+    })
+    return tabs
+  }
+
+}
+export default Tabs

package/src/appForTestingOnly.js

@@ -0,0 +1,15 @@
+import * as BrutJS from "./index.js"
+document.addEventListener("DOMContentLoaded", () => {
+  BrutJS.BrutCustomElements.define()
+  if (!HTMLDialogElement.prototype.showModal) {
+    HTMLDialogElement.prototype.showModal = function() {
+      this.open = true
+    }
+  }
+  if (!HTMLDialogElement.prototype.close) {
+    HTMLDialogElement.prototype.close = function(returnValue) {
+      this.open = false
+      this.returnValue = returnValue
+    }
+  }
+})

package/src/index.js

@@ -0,0 +1,119 @@
+import BaseCustomElement           from "./BaseCustomElement"
+import RichString                  from "./RichString"
+import AjaxSubmit                  from "./AjaxSubmit"
+import ConfirmSubmit               from "./ConfirmSubmit"
+import ConfirmationDialog          from "./ConfirmationDialog"
+import ConstraintViolationMessage  from "./ConstraintViolationMessage"
+import ConstraintViolationMessages from "./ConstraintViolationMessages"
+import Form                        from "./Form"
+import I18nTranslation             from "./I18nTranslation"
+import Message                     from "./Message"
+import Tabs                        from "./Tabs"
+import LocaleDetection             from "./LocaleDetection"
+import Autosubmit                  from "./Autosubmit"
+
+/**
+ * This is the code for a test case. It may return a {@link external:Promise} if there is async behavior that must
+ * be waited-on to properly assert behavior.
+ *
+ * @callback testCodeCallback
+ *
+ * @param {Object} objects - objects passed into your test that you may need.
+ * @param {Window} objects.window - Access to the top-level window object. Note that this provided by JSDOM and is not exactly like the `Window` you'd get in your browser.
+ * @param {Document} objects.document - Access to the top-level document object. Note that this provided by JSDOM and is not exactly like the `Document` you'd get in your browser.
+ * @param {Object} objects.assert - The NodeJS assert object that you should use to assert behavior.
+ * @param {Object} objects.fetchRequests - An array of `Request` instances given to `fetch`.  This will be updated as `fetch` is
+ * called and can be useful to assert the contents of what was requested via `fetch`.
+ *
+ * @example
+ * test("some test", ({document,assert}) => {
+ *   const element = document.querySelector("div")
+ *   assert(div.getAttribute("data-foo") != null)
+ * })
+ *
+ * @example
+ * test("some other test", ({document,window,assert}) => {
+ *   const element = document.querySelector("div")
+ *   assert.equal(window.history.state["foo"], "bar")
+ * })
+ */
+
+/**
+ * @external Promise
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise|Promise}
+ */
+/**
+ * @external fetch
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch|fetch}
+ */
+
+/**
+ * @external ValidityState
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/ValidityState|ValidityState}
+ */
+
+/**
+ * The standard `CustomElementRegistry`
+ *
+ * @external CustomElementRegistry
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry|CustomElementRegistry}
+ */
+
+/**
+ * @external Window
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/|Window}
+ */
+
+/** 
+ * @method confirm
+ * @memberof external:Window#
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm|confirm}
+ */
+
+/**
+ * Class that can be used to automatically define all of brut's custom
+ * elements.
+ */
+class BrutCustomElements {
+  static elementClasses = []
+  static define() {
+    this.elementClasses.forEach( (e) => {
+      e.define() 
+    })
+  }
+  static addElementClasses(...classes) {
+    this.elementClasses.push(...classes)
+  }
+}
+
+BrutCustomElements.addElementClasses(
+  // Ordering is important here - TBD how to make sure these are created in order
+  I18nTranslation,
+  Message,
+  ConfirmSubmit,
+  ConfirmationDialog,
+  ConstraintViolationMessages,
+  Form,
+  AjaxSubmit,
+  ConstraintViolationMessage,
+  Tabs,
+  LocaleDetection,
+  Autosubmit,
+)
+
+export {
+  AjaxSubmit,
+  Autosubmit,
+  BaseCustomElement,
+  BrutCustomElements,
+  ConfirmSubmit,
+  ConfirmationDialog,
+  ConstraintViolationMessage,
+  ConstraintViolationMessages,
+  Form,
+  I18nTranslation,
+  LocaleDetection,
+  Message,
+  RichString,
+  Tabs
+}

package/src/testing/index.js

@@ -0,0 +1,348 @@
+/**
+ * Enables and implements a basic testing system for custom elements. This uses JSDOM and some hacks to allow
+ * you to test your custom elements using a DOM-like experience, but without having to run a real browser.
+ * It is designed to have very few dependencies to ensure the least amount of configuration and tool
+ * debt.
+ *
+ * It assumes you are using Mocha.  To create a test, create a file named `Whatever.spec.js` in the folder where you are running
+ * Mocha.  Convention is that `Whatever` is the name of your custom element's class.
+ *
+ * @example
+ * import { withHTML } from "../src/testing/index.js"
+ *
+ * describe("<some-element>", () => {
+ *   withHTML(`
+ *   <some-element>OK</some-element>
+ *   `).test("lower-cases its contents", ({document,assert}) => {
+ *     const element = document.querySelector("some-element")
+ *     assert.equal(element.textContent,"ok")
+ *   })
+ * })
+ *
+ * @module testing
+ */
+import { JSDOM, ResourceLoader, VirtualConsole } from "jsdom"
+import fs from "node:fs"
+import path from "node:path"
+import assert from "assert"
+
+const __dirname = import.meta.dirname
+
+const appRoot = path.resolve(__dirname,"..","..","specs")
+const publicRoot = path.resolve(appRoot,"public")
+
+class AssetMetadata {
+  constructor(parsedJSON, publicRoot) {
+    this.assetMetadata = parsedJSON.asset_metadata
+    this.publicRoot    = publicRoot
+  }
+
+  scriptURLs() {
+    return Object.entries(this.assetMetadata[".js"]).map( (entry) => {
+      return entry[0] 
+    })
+  }
+
+  fileContainingScriptURL(scriptURL) {
+    const file = Object.entries(this.assetMetadata[".js"]).find( (entry) => {
+      return entry[0] == scriptURL
+    })
+    if (!file || !file[1]) {
+      return null
+    }
+    let relativePath = file[1]
+    if (relativePath[0] == "/") {
+      relativePath = relativePath.slice(1)
+    }
+    return fs.readFileSync(path.resolve(this.publicRoot,relativePath))
+  }
+}
+
+const assetMetadata = new AssetMetadata(
+  JSON.parse(fs.readFileSync(path.resolve(appRoot,"config","asset_metadata.json"))),
+  publicRoot,
+)
+
+class AssetMetadataLoader extends ResourceLoader {
+  constructor(assetMetadata) {
+    super()
+    this.assetMetadata = assetMetadata
+  }
+
+  fetch(url,options) {
+    const parsedURL = new URL(url)
+    const jsContents = this.assetMetadata.fileContainingScriptURL(parsedURL.pathname)
+    if (jsContents) {
+      return Promise.resolve(jsContents)
+    }
+    else {
+      return super.fetch(url,options)
+    }
+  }
+}
+
+const resourceLoader = new AssetMetadataLoader(assetMetadata)
+
+const createDOM = (html, queryString) => {
+
+  const url = "http://example.com" + ( queryString ? `?${queryString}` : "" )
+
+  const scripts = assetMetadata.scriptURLs().map( (url) => `<script src="${url}"></script>` )
+  const virtualConsole = new VirtualConsole()
+  virtualConsole.sendTo(console);
+  return new JSDOM(
+    `<!DOCTYPE html>
+        <html>
+        <head>
+        ${scripts}
+        </head>
+        <body>
+        ${html}
+        </body>
+        </html>
+        `,{
+          resources: "usable",
+          runScripts: "dangerously",
+          includeNodeLocations: true,
+          resources: resourceLoader,
+          url: url
+        }
+  )
+}
+
+/**
+ * Returned by {@link withHTML} as the basis for writing tests for custom elements. You won't create
+ * instances of this class. Rather, you'll be given an instance from `withHTML` and likely call
+ * `test` on it.
+ *
+ * @see withHTML
+ */
+class CustomElementTest {
+  constructor(html, queryString) {
+    this.html          = html
+    this.queryString   = queryString
+    this.fetchBehavior = {}
+  }
+
+  /**
+   * Configure a query string to be present when the custom elements are defined and connected.
+   */
+  andQueryString(queryString) {
+    this.queryString = queryString
+    return this
+  }
+
+  /**
+   * Configure behavior when #{link external:fetch} is called, since it's not implemented by JSDom or NodeJS.
+   *
+   * @param {String} url - the URL that is expected. This should be a relative URL, as that is all that is currently supported. This
+   * URL must match exactly to a `fetch` call.
+   * @param {Object} behavior - an object describing what you want to happen when `url` is fetched.  This currently supports only a
+   * few rudimentary behaviors:
+   * * `{then: { ok: { text: "some text" } } }` - This will return an "ok" response whose body is the given text, available only as
+   * text.
+   * * `{then: { status: XXX, text: "some text" }}` - This will return the given http status, with `ok` as true if it's 2xx or 3xx. If `text` is given, that will be available as text only.
+   */
+  onFetch(url,behavior) {
+    if (!this.fetchBehavior[url]) {
+      this.fetchBehavior[url] = {
+        numCalls: 0,
+        responses: [],
+      }
+    }
+    if (behavior instanceof Array) {
+      behavior.forEach( (b) =>  {
+        this.fetchBehavior[url].responses.push(b)
+      })
+    }
+    else {
+      this.fetchBehavior[url].responses.push(behavior)
+    }
+    return this
+  }
+
+  /** Comment out a test without using code comments */
+  xtest() {
+    return this
+  }
+
+
+  /** Declare a test to run with the previously-defined HTML, query string, and fetch behavior.
+   *
+   * @param {String} description - a description of the test.
+   * @param {testCodeCallback} testCode - a function containing the code for your test.
+   */
+  test(description,testCode) {
+    it(description, () => {
+      const dom = createDOM(this.html,this.queryString)
+      const fetchRequests = []
+
+      dom.window.Request = Request
+      dom.window.fetch = (request) => {
+        const url = new URL(request.url)
+        const path = url.pathname + url.search
+        const behaviors = this.fetchBehavior[path]
+        if (!behaviors) {
+          throw `fetch() called with ${path}, which was not configured`
+        }
+        if (behaviors.numCalls > behaviors.responses.length) {
+          throw `fetch() called ${behaviors.numCalls} times, but we only have ${behaviors.response.length} responses configured`
+        }
+        const behavior = behaviors.responses[behaviors.numCalls]
+        behaviors.numCalls++
+
+        let promise = null
+
+        if (behavior.then) {
+          if (behavior.then.ok) {
+            if (behavior.then.ok.text) {
+              const response = {
+                ok: true,
+                text: () => {
+                  return Promise.resolve(behavior.then.ok.text)
+                }
+              }
+              promise = Promise.resolve(response)
+            }
+            else {
+              throw `unknown fetch behavior: expected then.ok.text: ${JSON.stringify(behavior)}`
+            }
+          }
+          else if (behavior.then.status) {
+            let ok = false
+            if ((behavior.then.status >= 200) && (behavior.then.status < 400) ){
+              ok = true
+            }
+            const response = {
+              ok: ok,
+              status: behavior.then.status,
+                text: () => {
+                  return Promise.resolve(behavior.then.text)
+                }
+            }
+            promise = Promise.resolve(response)
+          }
+          else {
+            throw `unknown fetch behavior: expected then.ok or then.status: ${JSON.stringify(behavior)}`
+          }
+        }
+        else {
+          throw `unknown fetch behavior: expected then: ${JSON.stringify(behavior)}`
+        }
+        request.promiseReturned = promise
+        fetchRequests.push(request)
+        return promise
+      }
+
+      const window = dom.window
+      const document = window.document
+      let returnValue = null
+      return new Promise( (resolve, reject) => {
+        dom.window.addEventListener("load", () => {
+          try {
+            returnValue = testCode({window,document,assert,fetchRequests})
+            if (returnValue) {
+              resolve(returnValue)
+            }
+            else {
+              resolve()
+            }
+          } catch (e) {
+            reject(e)
+          }
+        })
+      })
+    })
+    return this
+  }
+}
+
+/**
+ * Sets up the HTML in which a test will be run.  This allows you to configure what HTML will be "served"
+ * by JSDOM before any custom elements are defined or connected.
+ *
+ * This returns a {@link module:testing~CustomElementTest}, on which you can call additional setup methods, or start defining tests with the 
+ * {@link module:testing~CustomElementTest#test} method.
+ *
+ * @see module:testing~CustomElementTest
+ */
+const withHTML = (html) => new CustomElementTest(html)
+
+/**
+ * Given a fetch request (available via `fetchRequests` passed to your test), turn the body into JSON
+ * and return a promise with the JSON.  To use this in a test, you must include your assertions inside
+ * the `then` of the returned promise and you *must* return that from your test.
+ *
+ * @example
+ * withHTML(
+ *   "<div-makes-a-fetch>"
+ * ).onFetch("/foo", { then: { status: 200 }}
+ * ).test("a test",({assert,fetchRequests}) => {
+ *   assert.equal(fetchRequests.length,1)
+ *   return readRequestBodyIntoJSON(fetchRequests[0]).then( (json) => {
+ *     assert.equal(json["foo"],"bar")
+ *   })
+ * })
+ */
+const readRequestBodyIntoJSON = (request) => {
+  return readRequestBodyIntoString(request).then( (string) => {
+    try {
+      const json = JSON.parse(string)
+      return Promise.resolve(json)
+    }
+    catch (e) {
+      assert(false,`'${string}' could not be parsed as JSON`)
+    }
+    return Promise.resolve()
+  })
+}
+
+/**
+ * Given a fetch request (available via `fetchRequests` passed to your test), turn the body into a string
+ * and return a promise with the string.  To use this in a test, you must include your assertions inside
+ * the `then` of the returned promise and you *must* return that from your test.
+ *
+ * @example
+ * withHTML(
+ *   "<div-makes-a-fetch>"
+ * ).onFetch("/foo", { then: { status: 200 }}
+ * ).test("a test",({assert,fetchRequests}) => {
+ *   assert.equal(fetchRequests.length,1)
+ *   return readRequestBodyIntoString(fetchRequests[0]).then( (string) => {
+ *     assert.equal(string,"foo")
+ *   })
+ * })
+ */
+const readRequestBodyIntoString = (request) => {
+  const reader = request.body.getReader()
+  const utf8Decoder = new TextDecoder("utf-8");
+  let string = ""
+  const parse = ({value,done}) => {
+    if (done) {
+      return Promise.resolve(string)
+    }
+    else {
+      if (value) {
+        string = string + utf8Decoder.decode(value, { stream: true })
+      }
+      return reader.read().then(parse)
+    }
+  }
+  return reader.read().then(parse)
+}
+
+/** Used to wait for a few milliseconds before performing further assertions.
+ * This can be useful when a custom element has `setTimeout` calls
+ */
+const waitForSetTimeout = (ms) => {
+  return new Promise( (resolve) => {
+    setTimeout(resolve,ms)
+  })
+}
+
+export {
+  withHTML,
+  readRequestBodyIntoJSON,
+  readRequestBodyIntoString,
+  waitForSetTimeout,
+}