brut 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 740d14b192a1f496bec06f3154a761ecd0bfaf0e838a6b8b156eda122e625c32
-  data.tar.gz: 5c4d510c355c4c08b5ea71b984fe6fc14d6a029c9e185ca48f3040bb3a166cc4
+  metadata.gz: 6ddbdd2db5bb6ea9013486bc8ad279affec3d3a824d05ebbd8c4b4933a1c5468
+  data.tar.gz: 823232c021e8c3d5477bc5655fefe6b51c54efcfcc73ca2ad0cab535964a23f1
 SHA512:
-  metadata.gz: 84a9428fbf87c5cb6e37303b23a508ab603936d67a276a9a60793944d3d29ef296e749d5cddb04b45ddf28250f6d35557514c9c8dcd579f9ca5aaf9538af9f78
-  data.tar.gz: 39a687879cacc21c3c73d6ad948c0e307c13fa8dcee31575aef02e39ce0b3f45e07a81c30876a83dcdd7a1c66e4bac917cbeb80be2437fcdada2f6066fa3e49f
+  metadata.gz: 152283ed984e5c7c8cd8faebdc5efbb24867efbe9a18a02a6896ab28654cc9b2b5fa39fe1ac9a13a6d477bd34ec3cb42a96034492d317f5355eb9e4434825395
+  data.tar.gz: 52b69e78ad33ceb908bb6617960a33022f36df621b5d9f3da327a167600cd0c9dbc1902d90d86ec0bdfbef400fa3fded9261b4980feb2dd4264d5c87afb7535f

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Brut CHANGELOG
 
+## v0.5.0 - July 21, 2025
+
+* **New helper** `entity` for creating HTML entities without needing `raw(safe(...))`
+
+  ```ruby
+  # BEFORE
+  a(href:HomePage.routing) do
+    raw(safe("←"))
+    whitespace
+    plain("Back")
+  end
+
+  # AFTER
+  a(href:HomePage.routing) do
+    entity("larr")  # <----
+    whitespace
+    plain("Back")
+  end
+  ```
+
+* Insturment each component's `view_template` method to give a breakdown on 
+  performance per component
+* Added a few additional events for tracing
+* Fix bug in `bin/scaffold db_model` where `implementation_is_trivial` was misspelled
+
+## v0.4.0 - July 12, 2025 and July 16, 2025 (see note)
+
+* **Breaking Change** - changed `cv.fe` and `cv.be` I18n keys to `cv.cs` and `cv.ss`
+  - This is to be consistent with Brut terminology
+  - To address this change:
+    1. Update brut-js to 0.0.22
+    2. Modify your `app/config/*/*.rb` i18n files to change `cv:` to `cs:` and `be:`
+       to `ss:`
+    3. Change `app/src/front_end/layouts/default_layout.rb`:
+
+       ```diff
+       -        I18nTranslations("cv.fe")
+       +        I18nTranslations("cv.cs")
+       ```
+    4. Change anywhere in your code or tests that you refer to those keys
+* Added `#valid?` to `Brut::FrontEnd::Form` to make it easier to check a lack
+  of constraint violations
+* Added response body to `<brut-ajax-submit>`
+
+**NOTE:** BrutJS and BrutCSS versions were changed to 0.4.0 on July 16 to mirror the Brut RubyGem. Intention is to keep all three in sync to avoid confusion about what the versions mean.
+
 ## v0.3.1 - July 12, 2025
 
 * **`bin/db new_migration` includes link to the migrations recipe**

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    brut (0.3.1)
+    brut (0.5.0)
       concurrent-ruby
       i18n
       irb

data/brut-css/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "brut-css",
-  "version": "0.0.1",
+  "version": "0.5.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "brut-css",
-      "version": "0.0.1",
+      "version": "0.5.0",
       "license": "Hippocratic-2.1",
       "devDependencies": {
         "comment-parser": "^1.4.1",

data/brut-css/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brut-css",
-  "version": "0.0.1",
+  "version": "0.5.0",
   "description": "Utility CSS Library for Full Stack Developers",
   "keywords": [
     "css"

data/brut-css/src/css/flex.css

@@ -138,7 +138,7 @@
 }
 /* Flex shrink, using a six-step scale.
  *
- * @scale flex-grow
+ * @scale flex-shrink
  */
 .flex-shrink-0 {
   flex-shrink: 0;

data/brut-css/src/docs/includes/body-and-header.html.ejs

@@ -3,7 +3,7 @@
       <div class="flex gap-3 justify-between items-center">
         <h1><a href="<%= pathToBrutCSSRoot %>" class="black tdn">BrutCSS Reference Documentation</a></h1>
         <ul class="lst-none pl-0 flex gap-2 justify-end items-center">
-          <form class="flex items-center gap-1 mr-3">
+          <form class="dn flex items-center gap-1 mr-3">
             <label>
             <input type="search" placeholder="e.g. padding-left" class="pa-2 br-2 ba bc-gray-600 bg-white-ish gray-200">
             <span class="sr-only">Search term</span>

data/brut-js/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "brut-js",
-  "version": "0.0.21",
+  "version": "0.5.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "brut-js",
-      "version": "0.0.21",
+      "version": "0.5.0",
       "license": "Hippocratic-2.1",
       "devDependencies": {
         "esbuild": "^0.24.0",

data/brut-js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brut-js",
-  "version": "0.0.21",
+  "version": "0.5.0",
   "type": "module",
   "keywords": [ "WebComponents", "Custom Elements" ],
   "bugs": {

data/brut-js/specs/AjaxSubmit.spec.js

@@ -10,7 +10,7 @@ describe("<brut-ajax-submit>", () => {
       </brut-ajax-submit>
     </form>
   `).onFetch( "/foo", [
-    { then: { status: 200 }},
+    { then: { status: 200, text: "<div>some html</div>" }},
   ]
   ).test("submits the form, setting various attributes during the lifecycle", 
          ({document,assert,fetchRequests,waitForSetTimeout,readRequestBodyIntoString}) => {
@@ -21,8 +21,10 @@ describe("<brut-ajax-submit>", () => {
     const number  = document.querySelector("input[name=some-number]")
 
     let okReceived = false
-    element.addEventListener("brut:submitok", () => {
+    let detailReceived = null
+    element.addEventListener("brut:submitok", (event) => {
       okReceived = true
+      detailReceived = event.detail
     })
 
     text.value   = "Some Text"
@@ -37,6 +39,8 @@ describe("<brut-ajax-submit>", () => {
 
     return Promise.all(promises).then( () => {
       assert(okReceived)
+      assert(detailReceived)
+      assert.equal(detailReceived.body.innerHTML,"<div>some html</div>")
       assert(element.getAttribute("requesting") == null)
       assert(element.getAttribute("submitted") != null)
       waitForSetTimeout(11).then( () => {
@@ -58,7 +62,7 @@ describe("<brut-ajax-submit>", () => {
     const number  = form.querySelector("input[name=some-number]")
 
     let okReceived = false
-    element.addEventListener("brut:submitok", () => {
+    element.addEventListener("brut:submitok", (event) => {
       okReceived = true
     })
 
@@ -204,16 +208,22 @@ Error that should be ignored
       }
     },
   ]
-  ).test("when we get a 422, parses the result from the server", ({document,window,assert,fetchRequests,waitForSetTimeout}) => {
+  ).test("when we get a 422, parses the result from the server and inserts them into the DOM, event detail is null", ({document,window,assert,fetchRequests,waitForSetTimeout}) => {
     const form    = document.querySelector("form")
     const element = form.querySelector("brut-ajax-submit")
     const button  = element.querySelector("button")
     const text    = form.querySelector("input[name=some-text]")
     const number  = form.querySelector("input[name=some-number]")
 
-    let okReceived = 0
+    let okReceived = false
+    let submittedInvalidReceived = false
+    let submittedInvalidDetail = "not null"
     element.addEventListener("brut:submitok", () => {
-      okReceived++
+      okReceived = true
+    })
+    element.addEventListener("brut:submitinvalid", (event) => {
+      submittedInvalidReceived = true
+      submittedInvalidDetail = event.detail
     })
 
     text.value   = "Some Text"
@@ -227,7 +237,9 @@ Error that should be ignored
         map( (fetchRequest) => fetchRequest.promiseReturned )
 
       return Promise.all(promises).then( () => {
-        assert.equal(okReceived,0)
+        assert(!okReceived)
+        assert( submittedInvalidReceived)
+        assert(!submittedInvalidDetail)
         const textFieldErrors = form.querySelectorAll("brut-cv-messages[input-name='some-text'] brut-cv")
         assert.equal(3,textFieldErrors.length) // prevous client-side and 2 new server-side
         const serverSideTextFieldErrors = form.querySelectorAll("brut-cv-messages[input-name='some-text'] brut-cv[server-side]")
@@ -253,4 +265,85 @@ Error that should be ignored
       })
     })
   })
+  withHTML(`
+    <form action="http://example.net/foo" method="POST">
+
+      <input required type="text" name="some-text">
+      <brut-cv-messages input-name="some-text">
+        <brut-cv input-name="some-text">
+        A client-side-error
+        </brut-cv>
+        <brut-cv server-side input-name="some-text">
+        A previous server-side-error
+        </brut-cv>
+      </brut-cv-messages>
+
+      <input required type="number" name="some-number">
+      <brut-cv-messages input-name="some-number">
+      </brut-cv-messages>
+
+      <brut-ajax-submit submitted-lifetime="10" no-server-side-error-parsing>
+        <button>Submit</button>
+      </brut-ajax-submit>
+    </form>
+  `).onFetch( "/foo", [
+    {
+      then: {
+        status: 422,
+        text: `
+<brut-cv input-name="some-text">
+A sever-side error
+</brut-cv>
+<brut-cv input-name="some-text">
+Another sever-side error
+</brut-cv>
+<brut-cv input-name="some-other-text">
+Irrelevant server-side error
+</brut-cv>
+<brut-cv>
+Error that should be ignored
+</brut-cv>
+<div>element that should be ignored</div>
+        `
+      }
+    },
+  ]
+  ).test("when we get a 422, does not parse the results, but includes them in the detail", ({document,window,assert,fetchRequests,waitForSetTimeout}) => {
+    const form    = document.querySelector("form")
+    const element = form.querySelector("brut-ajax-submit")
+    const button  = element.querySelector("button")
+    const text    = form.querySelector("input[name=some-text]")
+    const number  = form.querySelector("input[name=some-number]")
+
+    let okReceived = false
+    let submittedInvalidReceived = false
+    let submittedInvalidDetail = null
+    element.addEventListener("brut:submitok", () => {
+      okReceived = true
+    })
+    element.addEventListener("brut:submitinvalid", (event) => {
+      submittedInvalidReceived = true
+      submittedInvalidDetail = event.detail
+    })
+
+    text.value   = "Some Text"
+    number.value = "11"
+
+    button.click()
+    return waitForSetTimeout(5).then( () => {
+
+      const promises = fetchRequests.
+        filter( (fetchRequest) => fetchRequest.promiseReturned ).
+        map( (fetchRequest) => fetchRequest.promiseReturned )
+
+      return Promise.all(promises).then( () => {
+        assert(!okReceived)
+        assert( submittedInvalidReceived)
+        assert.equal(submittedInvalidDetail.body.children.length,5)
+        const textFieldErrors = form.querySelectorAll("brut-cv-messages[input-name='some-text'] brut-cv")
+        assert.equal(2,textFieldErrors.length) // what was initially rendered
+
+      })
+    })
+  })
 })

data/brut-js/specs/ConstraintViolationMessage.spec.js

@@ -23,7 +23,7 @@ describe("<brut-cv>", () => {
   withHTML(`
     <brut-i18n-translation key="problem"                     value="%{field} has a problem"></brut-i18n-translation>
     <brut-i18n-translation key="cv.this_field"               value="THAT FIELD"></brut-i18n-translation>
-    <brut-i18n-translation key="cv.fe.fieldNames.some-field" value="Some Field"></brut-i18n-translation>
+    <brut-i18n-translation key="cv.cs.fieldNames.some-field" value="Some Field"></brut-i18n-translation>
 
     <brut-cv input-name="some-field" key="problem"></brut-cv>
   `).test("Inserts using the this_field key as the placeholder", ({document,assert}) => {

data/brut-js/specs/ConstraintViolationMessages.spec.js

@@ -2,8 +2,8 @@ import { withHTML } from "./SpecHelper.js"
 
 describe("<brut-cv-messages>", () => {
   withHTML(`
-    <brut-i18n-translation key="cv.fe.patternMismatch" value="%{field} does not match the pattern"></brut-i18n-translation>
-    <brut-i18n-translation key="cv.fe.rangeOverflow" value="%{field} is above the range"></brut-i18n-translation>
+    <brut-i18n-translation key="cv.cs.patternMismatch" value="%{field} does not match the pattern"></brut-i18n-translation>
+    <brut-i18n-translation key="cv.cs.rangeOverflow" value="%{field} is above the range"></brut-i18n-translation>
 
     <brut-cv-messages input-name="some-field"></brut-cv-messages>
   `).test("Inserts constraint violation messages based on validity state", ({document,assert}) => {

data/brut-js/specs/Form.spec.js

@@ -51,9 +51,9 @@ describe("<brut-form>", () => {
     assert(gotInvalid)
     assert.equal(brutForm.getAttribute("submitted-invalid"),"")
 
-    let error = textFieldLabel.querySelector("brut-cv[key='cv.fe.valueMissing']")
+    let error = textFieldLabel.querySelector("brut-cv[key='cv.cs.valueMissing']")
     assert(error)
-    error = numberFieldLabel.querySelector("brut-cv[key='cv.fe.valueMissing']")
+    error = numberFieldLabel.querySelector("brut-cv[key='cv.cs.valueMissing']")
     assert(error)
 
     const textField = textFieldLabel.querySelector("input")
@@ -71,9 +71,9 @@ describe("<brut-form>", () => {
     assert(gotInvalid)
     assert.equal(brutForm.getAttribute("submitted-invalid"),"")
 
-    error = textFieldLabel.querySelector("brut-cv[key='cv.fe.valueMissing']")
+    error = textFieldLabel.querySelector("brut-cv[key='cv.cs.valueMissing']")
     assert(!error)
-    error = numberFieldLabel.querySelector("brut-cv[key='cv.fe.valueMissing']")
+    error = numberFieldLabel.querySelector("brut-cv[key='cv.cs.valueMissing']")
     assert(error)
 
     const numberField = numberFieldLabel.querySelector("input")
@@ -174,7 +174,7 @@ describe("<brut-form>", () => {
     assert(gotInvalid)
     assert.equal(brutForm.getAttribute("submitted-invalid"),"")
 
-    let error = brutForm.querySelector("brut-cv[input-name='text'][key='cv.fe.valueMissing']")
+    let error = brutForm.querySelector("brut-cv[input-name='text'][key='cv.cs.valueMissing']")
     assert(error)
 
   })

data/brut-js/src/AjaxSubmit.js

@@ -13,7 +13,13 @@ import ConstraintViolationMessage from "./ConstraintViolationMessage"
  * 4. If the request returns OK:
  *    - `requesting` will be removed and `submitted` will be added.
  *    - `submitted` will be removed after `submitted-lifetime` ms.
- * 5. If the request returned a 422, error messages are parsed. See below.
+ *    - the `brut:submitok` event will be fired with the response text, **parsed as HTML**, as `event.detail`.
+ * 5. If the request returned a 422:
+ *    - If you have set `no-server-side-error-parsing`, the results will be included in the 
+ *      detail field of the `brut:submitinvalid` event.
+ *    - If you have NOT set `no-server-side-error-parsing`, the response is parsed as
+ *      errors to be inserted into the DOM.  See below for how that works.  In this case,
+ *      `brut:submitinvalid`'s detail bill be null.
  * 6. If the request returns not OK and not 422:
  *    - if it has been `request-timeout` ms or more since the button was first clicked, the operation is aborted (see below).
  *    - if it has been less than `request-timeout` ms and the HTTP status code was 5xx, the operation is retried.
@@ -23,7 +29,8 @@ import ConstraintViolationMessage from "./ConstraintViolationMessage"
  * Aborting the operation will submit the form in the normal way, allowing the browser to deal with whatever the issue is. You can set
  * `log-request-errors` to introspect this process.
  *
- * For a 422 response, this element assumes the response is `text/html` and contains one or more `<brut-cv>`
+ * For a 422 response (where `no-server-side-error-parsing` is *not* set),
+ * this element assumes the response is `text/html` and contains one or more `<brut-cv>`
  * elements.  These elements will be inserted into the proper `<brut-cv-messages>` element, as follows:
  *
  * 1. The `input-name` is examined.
@@ -37,6 +44,17 @@ import ConstraintViolationMessage from "./ConstraintViolationMessage"
  * 9. The first input located is scrolled into view
  * 10. If the input is modified after this all happens, custom validity is cleared
  *
+ * For the server you are contacting, this element has a few requirements:
+ *
+ * - If everything is OK/the operation did what it was intended to do:
+ *   - the server will respond with a 2xx
+ *   - the response body, if it contains anything, be `text/html` (this is provided in the event detail)
+ * - If there are server-side constraint violations.
+ *   - the server will return 422
+ *   - the response body will be `text/html`
+ *   - the response body will contain one or more `<brut-cv>` elements
+ *
+ * @property {boolean} no-server-side-error-parsing - if set, the response body for a 422 will not be parsed and inserted into the DOM. Instead, the body will be part of the detail of the `brut:submitinvalid` event.
  * @property {number} request-timeout - number of ms that the entire operation is expected to complete within. Default is 5000
  * @property {number} submitted-lifetime - number of ms that "submitted" should remain on the element after the form has completed. Default is 2000
  * @property {boolean} requesting - boolean attribute that indicates the request has been made, but not yet returned. Don't set this yourself outside of development. It will be set and removed by this element.
@@ -44,8 +62,8 @@ import ConstraintViolationMessage from "./ConstraintViolationMessage"
  * @property {boolean} log-request-errors - if set, logging related to request error handling will appear in the console. It will also
  * cause any form submission to be delayed by 2s to allow you to read the console.
  *
- * @fires brut:submitok Fired when the AJAX request initated by this returns OK and all processing has completed
- * @fires brut:submitinvalid Fired when the AJAX request initated by this returns a 422 and all logic around managing the reponse has completed
+ * @fires brut:submitok Fired when the AJAX request initated by this returns OK and all processing has completed. The detail will include the *parsed document* of the HTML returned in the response.
+ * @fires brut:submitinvalid Fired when the AJAX request initated by this returns a 422 and all logic around managing the reponse has completed. The detail will be null unless `no-server-side-error-parsing` is set, in which case it will be the parsed document of the HTML returned in the response.
  *
  * @example
  * <form action="/widgets" method="post">
@@ -68,6 +86,7 @@ class AjaxSubmit extends BaseCustomElement {
     "request-timeout",
     "max-retry-attempts",
     "log-request-errors",
+    "no-server-side-error-parsing",
   ]
 
   #requestErrorLogger = () => {}
@@ -75,6 +94,12 @@ class AjaxSubmit extends BaseCustomElement {
   #submittedLifetime  = 2000
   #requestTimeout     = 5000
   #maxRetryAttempts   = 25
+  #serverSideErrorParsing = true
+
+  constructor() {
+    super()
+    this.domParser = new DOMParser()
+  }
 
   submittedLifetimeChangedCallback({newValue}) {
     const newValueAsInt = parseInt(newValue)
@@ -84,6 +109,10 @@ class AjaxSubmit extends BaseCustomElement {
     this.#submittedLifetime = newValueAsInt
   }
 
+  noServerSideErrorParsingChangedCallback({newValueAsBoolean}) {
+    this.#serverSideErrorParsing = !newValueAsBoolean
+  }
+
   maxRetryAttemptsChangedCallback({newValue}) {
     const num = parseInt(newValue)
     if (isNaN(num)) {
@@ -187,7 +216,10 @@ class AjaxSubmit extends BaseCustomElement {
         this.setAttribute("submitted",true)
 
         setTimeout( () => this.removeAttribute("submitted"), this.#submittedLifetime )
-        this.dispatchEvent(new CustomEvent("brut:submitok"))
+        response.text().then( (text) =>  {
+          const parsedDocument = this.domParser.parseFromString(text,"text/html")
+          this.dispatchEvent(new CustomEvent("brut:submitok", { detail: parsedDocument }))
+        })
       }
       else {
 
@@ -250,49 +282,53 @@ class AjaxSubmit extends BaseCustomElement {
   #handleConstraintViolations(response) {
     let resubmit = false
     response.text().then( (text) => {
-      try {
-        const inputsToMessages = ErrorMessagesForInput.mapInputsToErrorMessages(
-          this.#errorMessagesFromServer(text),
-          this.#requestErrorLogger
-        )
+      const parsedDocument = this.domParser.parseFromString(text,"text/html")
+      let event
+      if (this.#serverSideErrorParsing) {
+        event = new CustomEvent("brut:submitinvalid")
+      }
+      else {
+        event = new CustomEvent("brut:submitinvalid", { detail: parsedDocument })
+      }
+      this.dispatchEvent(event)
+      if (this.#serverSideErrorParsing) {
+        const constraintViolationNodes = parsedDocument.querySelectorAll(ConstraintViolationMessage.tagName)
+        try {
+          const inputsToMessages = ErrorMessagesForInput.mapInputsToErrorMessages(
+            constraintViolationNodes,
+            this.#requestErrorLogger
+          )
+
+          let inputToScrollToAfterReportingValidity
+          for (const [inputName, {input, messagesElement, errorMessages}] of Object.entries(inputsToMessages)) {
+            if (!inputToScrollToAfterReportingValidity) {
+              inputToScrollToAfterReportingValidity = input
+            }
+            messagesElement.clearServerSideMessages()
+            errorMessages.forEach( (element) => {
+              ConstraintViolationMessage.markServerSide(element)
+              messagesElement.appendChild(element) 
+            })
+            this.#setCustomValidityThatClearsOnChange(input,errorMessages)
+          }
 
-        let inputToScrollToAfterReportingValidity
-        for (const [inputName, {input, messagesElement, errorMessages}] of Object.entries(inputsToMessages)) {
-          if (!inputToScrollToAfterReportingValidity) {
-            inputToScrollToAfterReportingValidity = input
+          if (inputToScrollToAfterReportingValidity) {
+            inputToScrollToAfterReportingValidity.scrollIntoView()
           }
-          messagesElement.clearServerSideMessages()
-          errorMessages.forEach( (element) => {
-            ConstraintViolationMessage.markServerSide(element)
-            messagesElement.appendChild(element) 
-          })
-          this.#setCustomValidityThatClearsOnChange(input,errorMessages)
+          resubmit = false
+          this.removeAttribute("requesting")
         }
-
-        if (inputToScrollToAfterReportingValidity) {
-          inputToScrollToAfterReportingValidity.scrollIntoView()
+        catch (e) {
+          this.#requestErrorLogger("While parsing %s, got %s", text, e)
+          resubmit = true
+        }
+        if (resubmit) {
+          this.#submitFormThroughBrowser(form)
         }
-        resubmit = false
-        this.removeAttribute("requesting")
-        this.dispatchEvent(new CustomEvent("brut:submitinvalid"))
-      }
-      catch (e) {
-        this.#requestErrorLogger("While parsing %s, got %s", text, e)
-        resubmit = true
-      }
-      if (resubmit) {
-        this.#submitFormThroughBrowser(form)
       }
     })
   }
 
-  #errorMessagesFromServer(text) {
-    const parser   = new DOMParser()
-    const fragment = parser.parseFromString(text,"text/html")
-
-    return fragment.querySelectorAll(ConstraintViolationMessage.tagName)
-  }
-
   #setCustomValidityThatClearsOnChange(input,errorMessages) {
     input.setCustomValidity(errorMessages[0].textContent)
     input.reportValidity()

data/brut-js/src/ConstraintViolationMessage.js

@@ -7,7 +7,7 @@ import I18nTranslation from "./I18nTranslation"
  *
  * 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»`.
+ * 1. It will look for a `<brut-i18n-translation>` element with the `key` `cv.cs.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.
@@ -37,7 +37,7 @@ class ConstraintViolationMessage extends BaseCustomElement {
 
   static createElement(document,attributes) {
     const element = document.createElement(ConstraintViolationMessage.tagName)
-    element.setAttribute("key",this.i18nKey("fe", attributes.key))
+    element.setAttribute("key",this.i18nKey("cs", attributes.key))
     element.setAttribute("input-name",attributes["input-name"])
     if (Object.hasOwn(attributes,"show-warnings")) {
       element.setAttribute("show-warnings",attributes["show-warnings"])
@@ -79,7 +79,7 @@ class ConstraintViolationMessage extends BaseCustomElement {
   }
 
   inputNameChangedCallback({newValue}) {
-    this.#inputNameKey = this.#i18nKey("fe", "fieldNames", newValue)
+    this.#inputNameKey = this.#i18nKey("cs", "fieldNames", newValue)
   }
 
   serverSideChangedCallback({newValueAsBoolean}) {

data/brut-js/src/ConstraintViolationMessages.js

@@ -38,9 +38,9 @@ class ConstraintViolationMessages extends BaseCustomElement {
    * This should be called as part of a Form validation event to provide a customized UX for
    * the error messages, beyond what the browser would do by default.  The keys used are the same
    * as the attributes of a `ValidityState`, so for example, a range underflow would mean that `validity.rangeUnderflow` would return
-   * true.  Thus, a `<brut-cv>` would be created with `key="cv.fe.rangeUnderflow"`.
+   * true.  Thus, a `<brut-cv>` would be created with `key="cv.cs.rangeUnderflow"`.
    *
-   * The `cv.fe` is hard-coded to be consistent with Brut's server-side translation management.
+   * 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`.

data/brutrb.com/adrs.md

@@ -13,3 +13,4 @@ them, and mostly hold up.
 * [Brut will not provider mailers, cloud storage, or background jobs](https://adrs.cloud/shared_adrs/padr_e7078d29f00710848ebbe43aea6094a6)
 * [Requiring files should not execute code](https://adrs.cloud/shared_adrs/padr_03b5cf8e34bb7900a38f6de27e50adaa)
 * [Phlex will be used for HTML templating](https://adrs.cloud/shared_adrs/padr_9529a5ada671254b5e5865b45abde92d)
+* [RSpec is the default testing framework](https://adrs.cloud/shared_adrs/padr_724a65340d734970ea222593a4a2760f)

data/brutrb.com/database-schema.md

@@ -19,8 +19,7 @@ Brut's provides this via Sequel. See [both](https://sequel.jeremyevans.net/rdoc/
 
 ### Creating Migrations
 
-To create a migration, use `bin/db new-migration`. It accepts any  number of arguments that will be joined
-together to form the filename:
+To create a migration, use `bin/db new-migration`. It accepts any  number of arguments that will be joined together to form the filename:
 
 ```
 > bin/db new-migration user accounts
@@ -28,6 +27,27 @@ together to form the filename:
     app/src/back_end/data_models/migrations/20250508132646_user-accounts.rb
 ```
 
+If you will be creating [database models](/database-access) as well, you may find it
+easier to use `bin/scaffold db_model`, which will create an empty database model
+class, empty test, and empty factory, along with an outline of your migration:
+
+```
+bin/scaffold db_model widget
+[ bin/scaffold ] Executing ["bin/db new_migration create_widget"]
+[ bin/db ] Migration created:
+    app/src/back_end/data_models/migrations/20250712182257_create_widgets.rb
+[ bin/scaffold ] ["bin/db new_migration create_widgets"] succeeded
+[ bin/scaffold ] Creating DB::Foo in app/src/back_end/data_models/db/widget.rb
+[ bin/scaffold ] Creating spec for DB::Foo in specs/back_end/data_models/db/widget.spec.rb
+[ bin/scaffold ] Creating factory for DB::Foo in specs/factories/db/widget.factory.rb
+```
+
+> [!IMPORTANT]
+> Brut doesn't do pluralization logic.  Although Sequel does do some, you should
+> not refer to your database model plurally. If you were do run `bin/scaffold
+> db_model widgets`, you'd create the class `DB::Widgets`, which would not work.
+> Be aware.
+
 Note that the files are located in `app/src/back_end/data_models/migrations` and
 have a name prefixed with a timestamp.  This timestamp determins an ordering of how
 the files are applied to the database.

data/brutrb.com/dev-environment.md

@@ -107,6 +107,7 @@ you full documentation about what the command and subcommands do.
 |                 | `custom_element_test` | Create a test for a custom element in your app                                            |
 |                 | `form`                | Create a form and handler                                                                 |
 |                 | `page`                | Create a new page and associated test                                                     |
+|                 | `db_model`            | Create one or more database models, specs, and factories, plus a migration to create the tables for those models |
 |                 | `test`                | Create the shell of a unit test based on an existing source file                          |
 |                 | `test:e2e`            | Create the shell of an end-to-end test                                                    |
 | <code style="white-space: nowrap">bin/test</code>      |                       | Run tests |