brut 0.0.29 → 0.2.0

data/docs/api/top-level-namespace.html

@@ -102,7 +102,7 @@
 </div>
 
       <div id="footer">
-  Generated on Fri Jul  4 21:27:27 2025 by
+  Generated on Thu Jul 10 13:41:03 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.4).
 </div>

data/docs/assets/adrs.md.JRxZ5uYE.js

@@ -0,0 +1 @@
+import{_ as r,c as a,o as d,ag as t}from"./chunks/framework.1L-BeKqY.js";const f=JSON.parse('{"title":"Architecture Decision Records","description":"","frontmatter":{},"headers":[],"relativePath":"adrs.md","filePath":"adrs.md"}'),s={name:"adrs.md"};function l(o,e,i,c,n,h){return d(),a("div",null,e[0]||(e[0]=[t('<h1 id="architecture-decision-records" tabindex="-1">Architecture Decision Records <a class="header-anchor" href="#architecture-decision-records" aria-label="Permalink to &quot;Architecture Decision Records&quot;">​</a></h1><p>The decisions here aren&#39;t <em>all</em> the architectural decisions I made, but are some of them, and mostly hold up.</p><p><code>adrs.cloud</code> is a Brut app.</p><ul><li><a href="https://adrs.cloud/shared_adrs/padr_b6920f0df907886b8a9207e9e2c9c2a2" target="_blank" rel="noreferrer">Rely on Web Standards and MDN Baseline</a></li><li><a href="https://adrs.cloud/shared_adrs/padr_57f2397009a8aaf2c6083813ca588d73" target="_blank" rel="noreferrer">The Core Abstraction is the Plain Old Class</a></li><li><a href="https://adrs.cloud/shared_adrs/padr_cdfcbe6b116b80a4f3d53fb3a6ed44b2" target="_blank" rel="noreferrer">Pages and Forms are First-Class Abstractions…not REST</a></li><li><a href="https://adrs.cloud/shared_adrs/padr_01810ba90a92ec6c081a81affe212fb2" target="_blank" rel="noreferrer">Sequel will provide the data layer and its models will only model the database</a></li><li><a href="https://adrs.cloud/shared_adrs/padr_f318e74925cb3e9d7e0eda329d085c4a" target="_blank" rel="noreferrer">There will be no controllers. Purpose-built classes will support pages, forms, and components.</a></li><li><a href="https://adrs.cloud/shared_adrs/padr_e7078d29f00710848ebbe43aea6094a6" target="_blank" rel="noreferrer">Brut will not provider mailers, cloud storage, or background jobs</a></li><li><a href="https://adrs.cloud/shared_adrs/padr_03b5cf8e34bb7900a38f6de27e50adaa" target="_blank" rel="noreferrer">Requiring files should not execute code</a></li><li><a href="https://adrs.cloud/shared_adrs/padr_9529a5ada671254b5e5865b45abde92d" target="_blank" rel="noreferrer">Phlex will be used for HTML templating</a></li></ul>',4)]))}const p=r(s,[["render",l]]);export{f as __pageData,p as default};

data/docs/assets/adrs.md.JRxZ5uYE.lean.js

@@ -0,0 +1 @@
+import{_ as r,c as a,o as d,ag as t}from"./chunks/framework.1L-BeKqY.js";const f=JSON.parse('{"title":"Architecture Decision Records","description":"","frontmatter":{},"headers":[],"relativePath":"adrs.md","filePath":"adrs.md"}'),s={name:"adrs.md"};function l(o,e,i,c,n,h){return d(),a("div",null,e[0]||(e[0]=[t("",4)]))}const p=r(s,[["render",l]]);export{f as __pageData,p as default};

data/docs/assets/{ai.md._6HCDL6d.js → ai.md.Cy9GWnER.js}

@@ -1 +1 @@
-import{_ as t,c as o,o as a,ag as i}from"./chunks/framework.1L-BeKqY.js";const p=JSON.parse('{"title":"AI Declaration and Notes","description":"","frontmatter":{},"headers":[],"relativePath":"ai.md","filePath":"ai.md"}'),s={name:"ai.md"};function n(r,e,l,d,h,c){return a(),o("div",null,e[0]||(e[0]=[i('<h1 id="ai-declaration-and-notes" tabindex="-1">AI Declaration and Notes <a class="header-anchor" href="#ai-declaration-and-notes" aria-label="Permalink to &quot;AI Declaration and Notes&quot;">​</a></h1><p>LLMs and AI tools are a current fact of life. We feel it&#39;s important to be realistic and up front about how they affect this project.</p><h2 id="levels-of-ai-use" tabindex="-1">Levels of AI Use <a class="header-anchor" href="#levels-of-ai-use" aria-label="Permalink to &quot;Levels of AI Use&quot;">​</a></h2><p>I created <a href="https://declare-ai.org/" target="_blank" rel="noreferrer">declare-ai.org</a> to allow precise documentation of how AI is used in a project. It defines four levels of AI use:</p><ol><li>No involvement at all.</li><li>Non-create assistance, such as the completions GitHub Copilot may make while you are typing.</li><li>Creative assistance, where an AI generated a large amount of code that you then modified. An example would be using a tool like Cursor to write code for your review.</li><li>Completely Produced by an AI, for example if you used Stable Diffusion to create your icon.</li></ol><h2 id="code" tabindex="-1">Code <a class="header-anchor" href="#code" aria-label="Permalink to &quot;Code&quot;">​</a></h2><p>The entirety of Brut&#39;s codebase could be grouped into three parts:</p><ul><li>The library code developers use. This is, roughly, the code in <code>lib</code>, <code>brut-js/src</code>, and <code>brut-css/src</code>.</li><li>Tests of the library code.</li><li>Tools used to manage the library code, such as what&#39;s in <code>bin/</code>, <code>brut-js/bin</code>, <code>brut-css/bin</code>, etc.</li></ul><h3 id="library-code-should-be-written-by-a-person" tabindex="-1">Library Code Should Be Written By a Person <a class="header-anchor" href="#library-code-should-be-written-by-a-person" aria-label="Permalink to &quot;Library Code Should Be Written By a Person&quot;">​</a></h3><p>We want the library code written by a person, i.e. it should have level 1 AI assistance: none. As of this writing—June 17, 2025—all library code was written by a person.</p><p>If some code is level 2—non-creative assistance—that is probably fine.</p><h3 id="tests-should-not-be-totally-written-by-ai" tabindex="-1">Tests Should Not Be Totally Written by AI <a class="header-anchor" href="#tests-should-not-be-totally-written-by-ai" aria-label="Permalink to &quot;Tests Should Not Be Totally Written by AI&quot;">​</a></h3><p>As of this writing—June 17, 2025—the library has no automated tests. The <code>adrs.cloud</code> app serves as the test suite.</p><p>That said, as tests are developed, they must never be written entirely by an AI without human review (level 4). Our preference is that all tests comply with level 1 or level 2, however we are open to creative assistance for tests as might be provided by a tool like Cursor.</p><p>In any case, the author of a test should understand it and the maintainers must be able to understand and modify all tests without the use of AI tools.</p><h3 id="management-tools-should-not-be-totally-written-by-ai" tabindex="-1">Management Tools Should Not Be Totally Written by AI <a class="header-anchor" href="#management-tools-should-not-be-totally-written-by-ai" aria-label="Permalink to &quot;Management Tools Should Not Be Totally Written by AI&quot;">​</a></h3><p>Like tests, management tools must be comprehensible by a person and the creator of the code must understand it. That said, some of the tools were created with level 3 AI assistance, and we expect these tools may continue to be created this way.</p><p>Nevertheless, this code must be reviewed and understood by a person.</p><h2 id="documentation" tabindex="-1">Documentation <a class="header-anchor" href="#documentation" aria-label="Permalink to &quot;Documentation&quot;">​</a></h2><p>We strive to have all documentation written by a real person. None of this documentation, or the API documentation, is produced by a machine, although spelling and grammar corrections will certainly have been suggested by automated tools.</p><p>We expect an LLM to be able to digest this documentation and source code and provide alternate analysis of how Brut works and how to use it. We hope such analysis is correct and useful, however that cannot be guaranteed, so this documentation is the second best source of truth, the source code being the best.</p><h2 id="logo" tabindex="-1">Logo <a class="header-anchor" href="#logo" aria-label="Permalink to &quot;Logo&quot;">​</a></h2><p>The logo is level 4 - ChatGPT created it. I&#39;d love to have a real person make a better one. I just needed something to get this launched. Please reach out if you want to make a better one + other assets. I&#39;m willing to pay a real person.</p><h2 id="ai-completions-should-be-viewed-with-skepticism" tabindex="-1">AI Completions Should Be Viewed with Skepticism <a class="header-anchor" href="#ai-completions-should-be-viewed-with-skepticism" aria-label="Permalink to &quot;AI Completions Should Be Viewed with Skepticism&quot;">​</a></h2><p>Due to how LLMs work, there is naturally nothing in any model about Brut. Anything an existing model tells you about Brut is <strong>100% untrustworthy</strong>. We hope to allow LLMs to consume Brut&#39;s code, documentation, and examples, so it can be an additional source of help, but currently that is not the case.</p><p><strong>Do not ask an LLM about Brut</strong> until this part of the documentation changes.</p><p>For completion-based AI suggestions, <strong>view them with skepticism</strong>. In my experience, completions from e.g. GitHub CoPilot work OK when replicating a pattern in the file you are editing, but suggestions in a freshly-opened file tend to be entirely imaginary or Rails-based. Beware.</p>',27)]))}const b=t(s,[["render",n]]);export{p as __pageData,b as default};
+import{_ as t,c as o,o as a,ag as i}from"./chunks/framework.1L-BeKqY.js";const b=JSON.parse('{"title":"AI Declaration and Notes","description":"","frontmatter":{},"headers":[],"relativePath":"ai.md","filePath":"ai.md"}'),s={name:"ai.md"};function r(n,e,l,d,h,c){return a(),o("div",null,e[0]||(e[0]=[i('<h1 id="ai-declaration-and-notes" tabindex="-1">AI Declaration and Notes <a class="header-anchor" href="#ai-declaration-and-notes" aria-label="Permalink to &quot;AI Declaration and Notes&quot;">​</a></h1><p>LLMs and AI tools are a current fact of life. We feel it&#39;s important to be realistic and up front about how they affect this project.</p><h2 id="levels-of-ai-use" tabindex="-1">Levels of AI Use <a class="header-anchor" href="#levels-of-ai-use" aria-label="Permalink to &quot;Levels of AI Use&quot;">​</a></h2><p>I created <a href="https://declare-ai.org/" target="_blank" rel="noreferrer">declare-ai.org</a> to allow precise documentation of how AI is used in a project. It defines four levels of AI use:</p><ol><li>No involvement at all.</li><li>Non-create assistance, such as the completions GitHub Copilot may make while you are typing.</li><li>Creative assistance, where an AI generated a large amount of code that you then modified. An example would be using a tool like Cursor to write code for your review.</li><li>Completely Produced by an AI, for example if you used Stable Diffusion to create your icon.</li></ol><h2 id="code" tabindex="-1">Code <a class="header-anchor" href="#code" aria-label="Permalink to &quot;Code&quot;">​</a></h2><p>The entirety of Brut&#39;s codebase could be grouped into three parts:</p><ul><li>The library code developers use. This is, roughly, the code in <code>lib</code>, <code>brut-js/src</code>, and <code>brut-css/src</code>.</li><li>Tests of the library code.</li><li>Tools used to manage the library code, such as what&#39;s in <code>bin/</code>, <code>brut-js/bin</code>, <code>brut-css/bin</code>, etc.</li></ul><h3 id="library-code-should-be-written-by-a-person" tabindex="-1">Library Code Should Be Written By a Person <a class="header-anchor" href="#library-code-should-be-written-by-a-person" aria-label="Permalink to &quot;Library Code Should Be Written By a Person&quot;">​</a></h3><p>We want the library code written by a person, i.e. it should have level 1 AI assistance: none. As of this writing—June 17, 2025—all library code was written by a person.</p><p>If some code is level 2—non-creative assistance—that is probably fine.</p><h3 id="tests-should-not-be-totally-written-by-ai" tabindex="-1">Tests Should Not Be Totally Written by AI <a class="header-anchor" href="#tests-should-not-be-totally-written-by-ai" aria-label="Permalink to &quot;Tests Should Not Be Totally Written by AI&quot;">​</a></h3><p>As of this writing—June 17, 2025—the library has no automated tests. The <code>adrs.cloud</code> app serves as the test suite.</p><p>That said, as tests are developed, they must never be written entirely by an AI without human review (level 4). Our preference is that all tests comply with level 1 or level 2, however we are open to creative assistance for tests as might be provided by a tool like Cursor.</p><p>In any case, the author of a test should understand it and the maintainers must be able to understand and modify all tests without the use of AI tools.</p><h3 id="management-tools-should-not-be-totally-written-by-ai" tabindex="-1">Management Tools Should Not Be Totally Written by AI <a class="header-anchor" href="#management-tools-should-not-be-totally-written-by-ai" aria-label="Permalink to &quot;Management Tools Should Not Be Totally Written by AI&quot;">​</a></h3><p>Like tests, management tools must be comprehensible by a person and the creator of the code must understand it. That said, some of the tools were created with level 3 AI assistance, and we expect these tools may continue to be created this way.</p><p>Nevertheless, this code must be reviewed and understood by a person.</p><h2 id="documentation" tabindex="-1">Documentation <a class="header-anchor" href="#documentation" aria-label="Permalink to &quot;Documentation&quot;">​</a></h2><p>We strive to have all documentation written by a real person. None of this documentation, or the API documentation, is produced by a machine, although spelling and grammar corrections will certainly have been suggested by automated tools.</p><p>We expect an LLM to be able to digest this documentation and source code and provide alternate analysis of how Brut works and how to use it. We hope such analysis is correct and useful, however that cannot be guaranteed, so this documentation is the second best source of truth, the source code being the best.</p><h2 id="logos" tabindex="-1">Logos <a class="header-anchor" href="#logos" aria-label="Permalink to &quot;Logos&quot;">​</a></h2><p>While the various logos look like someone typed &quot;make me a logo in the style of the Washington, DC Metro&quot;, if you look closely, you will see the telltale sings that they were made by a person…a person who is not a professional designer.</p><p>As such, these are all Level 1.</p><h2 id="ai-information-about-brut-should-be-viewed-with-skepticism" tabindex="-1">AI Information about Brut Should Be Viewed with Skepticism <a class="header-anchor" href="#ai-information-about-brut-should-be-viewed-with-skepticism" aria-label="Permalink to &quot;AI Information about Brut Should Be Viewed with Skepticism&quot;">​</a></h2><ul><li><strong>Answers from an LLM about Brut are likely incorrect.</strong> LLMs will certainly not have been trained on information about Brut, since it is new.</li><li><strong>Code Completions of Brut Code are suspect.</strong> I have observed that e.g. GitHub CoPilot is capable for properly completing Brut code if there is enough context, but it is not capable of, say, creating a component from scratch. <strong>Review all Code Completions Carefully</strong>.</li></ul>',26)]))}const p=t(s,[["render",r]]);export{b as __pageData,p as default};

data/docs/assets/ai.md.Cy9GWnER.lean.js

@@ -0,0 +1 @@
+import{_ as t,c as o,o as a,ag as i}from"./chunks/framework.1L-BeKqY.js";const b=JSON.parse('{"title":"AI Declaration and Notes","description":"","frontmatter":{},"headers":[],"relativePath":"ai.md","filePath":"ai.md"}'),s={name:"ai.md"};function r(n,e,l,d,h,c){return a(),o("div",null,e[0]||(e[0]=[i("",26)]))}const p=t(s,[["render",r]]);export{b as __pageData,p as default};

data/docs/assets/{app.BhrfSt68.js → app.Dm3x-DQc.js}

@@ -1 +1 @@
-import{R as p}from"./chunks/theme.N2SNVLgU.js";import{R as s,a3 as i,a4 as u,a5 as c,a6 as l,a7 as f,a8 as d,a9 as m,aa as h,ab as g,ac as A,d as v,u as R,v as w,s as y,ad as C,ae as P,af as b,a2 as E}from"./chunks/framework.1L-BeKqY.js";function r(e){if(e.extends){const a=r(e.extends);return{...a,...e,async enhanceApp(t){a.enhanceApp&&await a.enhanceApp(t),e.enhanceApp&&await e.enhanceApp(t)}}}return e}const n=r(p),S=v({name:"VitePressApp",setup(){const{site:e,lang:a,dir:t}=R();return w(()=>{y(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&C(),P(),b(),n.setup&&n.setup(),()=>E(n.Layout)}});async function T(){globalThis.__VITEPRESS__=!0;const e=_(),a=D();a.provide(u,e);const t=c(e.route);return a.provide(l,t),a.component("Content",f),a.component("ClientOnly",d),Object.defineProperties(a.config.globalProperties,{$frontmatter:{get(){return t.frontmatter.value}},$params:{get(){return t.page.value.params}}}),n.enhanceApp&&await n.enhanceApp({app:a,router:e,siteData:m}),{app:a,router:e,data:t}}function D(){return A(S)}function _(){let e=s;return h(a=>{let t=g(a),o=null;return t&&(e&&(t=t.replace(/\.js$/,".lean.js")),o=import(t)),s&&(e=!1),o},n.NotFound)}s&&T().then(({app:e,router:a,data:t})=>{a.go().then(()=>{i(a.route,t.site),e.mount("#app")})});export{T as createApp};
+import{R as p}from"./chunks/theme.BXdlf6e8.js";import{R as s,a3 as i,a4 as u,a5 as c,a6 as l,a7 as f,a8 as d,a9 as m,aa as h,ab as g,ac as A,d as v,u as R,v as w,s as y,ad as C,ae as P,af as b,a2 as E}from"./chunks/framework.1L-BeKqY.js";function r(e){if(e.extends){const a=r(e.extends);return{...a,...e,async enhanceApp(t){a.enhanceApp&&await a.enhanceApp(t),e.enhanceApp&&await e.enhanceApp(t)}}}return e}const n=r(p),S=v({name:"VitePressApp",setup(){const{site:e,lang:a,dir:t}=R();return w(()=>{y(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&C(),P(),b(),n.setup&&n.setup(),()=>E(n.Layout)}});async function T(){globalThis.__VITEPRESS__=!0;const e=_(),a=D();a.provide(u,e);const t=c(e.route);return a.provide(l,t),a.component("Content",f),a.component("ClientOnly",d),Object.defineProperties(a.config.globalProperties,{$frontmatter:{get(){return t.frontmatter.value}},$params:{get(){return t.page.value.params}}}),n.enhanceApp&&await n.enhanceApp({app:a,router:e,siteData:m}),{app:a,router:e,data:t}}function D(){return A(S)}function _(){let e=s;return h(a=>{let t=g(a),o=null;return t&&(e&&(t=t.replace(/\.js$/,".lean.js")),o=import(t)),s&&(e=!1),o},n.NotFound)}s&&T().then(({app:e,router:a,data:t})=>{a.go().then(()=>{i(a.route,t.site),e.mount("#app")})});export{T as createApp};

data/docs/assets/{assets.md.D3wunzLx.js → assets.md.7C3HWkga.js}

@@ -1,4 +1,4 @@
-import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.1L-BeKqY.js";const u=JSON.parse('{"title":"Assets","description":"","frontmatter":{},"headers":[],"relativePath":"assets.md","filePath":"assets.md"}'),n={name:"assets.md"};function o(h,s,l,r,c,p){return i(),a("div",null,s[0]||(s[0]=[t(`<h1 id="assets" tabindex="-1">Assets <a class="header-anchor" href="#assets" aria-label="Permalink to &quot;Assets&quot;">​</a></h1><p>As mentioned in <a href="/javascript.html">Javascript</a> and <a href="/css.html">CSS</a>, esbuild is used to bundle JavaScript and CSS. Brut also provides support for managing images.</p><h2 id="javascript-and-css" tabindex="-1">JavaScript and CSS <a class="header-anchor" href="#javascript-and-css" aria-label="Permalink to &quot;JavaScript and CSS&quot;">​</a></h2><p>Both JavaScript and CSS are managed largely the same way: esbuild is given <code>app/src/front_end/js/index.js</code> or <code>app/src/front_end/css/index.css</code> and a bundle is produced.</p><p>For both JS and CSS, the bundles are <em>hashed</em>, even in development. This is to reduce differences in production and development. The <code>asset_path</code> helper can translate the logical path (<code>/js/app.js</code> or <code>/css/styles.css</code>) into the specific hashed path.</p><p>Sourcemaps are provided as well, for both development and production.</p><h3 id="what-is-hashing-and-why-do-it" tabindex="-1">What is Hashing and Why Do It? <a class="header-anchor" href="#what-is-hashing-and-why-do-it" aria-label="Permalink to &quot;What is Hashing and Why Do It?&quot;">​</a></h3><p>In production, while your pages produce dynamic data, the CSS and JavaScript bundles themselves are not dynamic. They are the same for every single request until you change them. Because of this, it&#39;s common to configure a cache for these files. Often, that cache is a <em>content delivery network</em> or CDN.</p><p>When a page is rendered, the browser will ask for the CSS and JS bundles. The CDN will tell the browser it&#39;s OK to cache the file, potentially for a very long time (years). On subsequent requests for those files, the browser will re-use its cached copy, saving bandwidth and time.</p><p>A downside of this approach is when you <em>do</em> want to change something. While most CDNs allow you to invalidate their cached values, there are many layers of caching whose behavior can be hard to control. It turns out to be much simpler to rename the file each you change it, thus &quot;breaking the cache&quot;.</p><p>A common way to do this is to create a hash of the file&#39;s contents and append that value to its name, so instead of <code>/static/css/styles.css</code>, the file would <code>/static/css/styles-98724fhjkjk.css</code>. When you make a change to your CSS, it&#39;ll get new name, say <code>/static/css/styles-3yjgdrjksrfdws.css</code>.</p><p>To keep you from having to deal with this directly, Brut&#39;s <code>asset_path</code> helper will translate a logical name like <code>/css/styles.css</code> to the actual name, like <code>/static/css/styles-3yjgdrjksrfdws.css</code>.</p><h3 id="what-are-sourcemaps-and-why-create-them" tabindex="-1">What are SourceMaps and Why Create Them? <a class="header-anchor" href="#what-are-sourcemaps-and-why-create-them" aria-label="Permalink to &quot;What are SourceMaps and Why Create Them?&quot;">​</a></h3><p>Bundled JavaScript and CSS will have been <em>minified</em>. This means removing whitespace, line breaks and, in the case of JavaScript, potentially changing the actual names of classes and variables. This is all to reduce the size of the file as much as possible without changing its meaning.</p><p>In your browser&#39;s dev tools, all your CSS is one the first line of <code>styles.css</code> and every stack trace from your JavaScript is on line 1 of <code>app.js</code>. This is not helpful for diagnosing issues.</p><p><em>SourceMaps</em> are separate files that translate the minified files back to normal ones, so you can see a normal stack trace with the actual line numbers of your source files.</p><p>There are many ways to create source maps and if you&#39;ve used a tool like WebPack, you&#39;ll recall that many of them don&#39;t produce usable source maps. Brut uses esbuild&#39;s facility for this, with a focus on correctness. When you see a line number and a source file in your browser, you can be sure it&#39;s accurate.</p><p>The tradeoff is that it can take longer to produce than producing an inaccurate one. I&#39;m not sure who wants inaccurate source maps, but Brut does not support this. In practice, esbuild is quite fast, so it should not make a practical difference in your day to day work.</p><h2 id="fonts" tabindex="-1">Fonts <a class="header-anchor" href="#fonts" aria-label="Permalink to &quot;Fonts&quot;">​</a></h2><p>Custom fonts are managed implicitly by esbuild&#39;s managing of CSS. In your CSS, you should reference fonts as relative to the CSS file. For example, if you have the font <code>app/src/front_end/fonts/monaspace-xenon.ttf</code>, then your <code>app/src/front_end/css/index.css</code> should look like so:</p><div class="language-css vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">css</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">@font-face</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.1L-BeKqY.js";const u=JSON.parse('{"title":"Assets","description":"","frontmatter":{},"headers":[],"relativePath":"assets.md","filePath":"assets.md"}'),n={name:"assets.md"};function o(h,s,l,r,p,d){return i(),a("div",null,s[0]||(s[0]=[t(`<h1 id="assets" tabindex="-1">Assets <a class="header-anchor" href="#assets" aria-label="Permalink to &quot;Assets&quot;">​</a></h1><p>As mentioned in <a href="/javascript.html">Javascript</a> and <a href="/css.html">CSS</a>, esbuild is used to bundle JavaScript and CSS. Brut also provides support for managing images.</p><h2 id="javascript-and-css" tabindex="-1">JavaScript and CSS <a class="header-anchor" href="#javascript-and-css" aria-label="Permalink to &quot;JavaScript and CSS&quot;">​</a></h2><p>Both JavaScript and CSS are managed largely the same way: esbuild is given <code>app/src/front_end/js/index.js</code> or <code>app/src/front_end/css/index.css</code> and a bundle is produced.</p><p>For both JS and CSS, the bundles are <em>hashed</em>, even in development. This is to reduce differences in production and development. The <code>asset_path</code> helper can translate the logical path (<code>/js/app.js</code> or <code>/css/styles.css</code>) into the specific hashed path.</p><p>Sourcemaps are provided as well, for both development and production.</p><h3 id="what-is-hashing-and-why-do-it" tabindex="-1">What is Hashing and Why Do It? <a class="header-anchor" href="#what-is-hashing-and-why-do-it" aria-label="Permalink to &quot;What is Hashing and Why Do It?&quot;">​</a></h3><p>In production, while your pages produce dynamic data, the CSS and JavaScript bundles themselves are not dynamic. They are the same for every single request until you change them. Because of this, it&#39;s common to configure a cache for these files. Often, that cache is a <em>content delivery network</em> or CDN.</p><p>When a page is rendered, the browser will ask for the CSS and JS bundles. The CDN will tell the browser it&#39;s OK to cache the file, potentially for a very long time (years). On subsequent requests for those files, the browser will re-use its cached copy, saving bandwidth and time.</p><p>A downside of this approach is when you <em>do</em> want to change something. While most CDNs allow you to invalidate their cached values, there are many layers of caching whose behavior can be hard to control. It turns out to be much simpler to rename the file each you change it, thus &quot;breaking the cache&quot;.</p><p>A common way to do this is to create a hash of the file&#39;s contents and append that value to its name, so instead of <code>/static/css/styles.css</code>, the file would <code>/static/css/styles-98724fhjkjk.css</code>. When you make a change to your CSS, it&#39;ll get new name, say <code>/static/css/styles-3yjgdrjksrfdws.css</code>.</p><p>To keep you from having to deal with this directly, Brut&#39;s <code>asset_path</code> helper will translate a logical name like <code>/css/styles.css</code> to the actual name, like <code>/static/css/styles-3yjgdrjksrfdws.css</code>.</p><h3 id="what-are-sourcemaps-and-why-create-them" tabindex="-1">What are SourceMaps and Why Create Them? <a class="header-anchor" href="#what-are-sourcemaps-and-why-create-them" aria-label="Permalink to &quot;What are SourceMaps and Why Create Them?&quot;">​</a></h3><p>Bundled JavaScript and CSS will have been <em>minified</em>. This means removing whitespace, line breaks and, in the case of JavaScript, potentially changing the actual names of classes and variables. This is all to reduce the size of the file as much as possible without changing its meaning.</p><p>In your browser&#39;s dev tools, all your CSS is one the first line of <code>styles.css</code> and every stack trace from your JavaScript is on line 1 of <code>app.js</code>. This is not helpful for diagnosing issues.</p><p><em>SourceMaps</em> are separate files that translate the minified files back to normal ones, so you can see a normal stack trace with the actual line numbers of your source files.</p><p>Brut&#39;s configuration of esbuild is to produce sourcemaps.</p><h2 id="fonts" tabindex="-1">Fonts <a class="header-anchor" href="#fonts" aria-label="Permalink to &quot;Fonts&quot;">​</a></h2><p>Custom fonts are managed implicitly by esbuild&#39;s managing of CSS. In your CSS, you should reference fonts as relative to the CSS file. For example, if you have the font <code>app/src/front_end/fonts/monaspace-xenon.ttf</code>, then your <code>app/src/front_end/css/index.css</code> should look like so:</p><div class="language-css vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">css</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">@font-face</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  font-family</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Monaspace Xenon&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line highlighted"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  src</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">url</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;../fonts/monaspace-xenon.ttf&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">format</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;truetype&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  font-display</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">swap</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
@@ -7,7 +7,7 @@ import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.1L-BeKqY.js";const u
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # Renders app/src/front_end/images/foo.png</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    img </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">src:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;/static/images/foo.png&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">alt:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Picture of a foo&quot;</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><h2 id="svgs" tabindex="-1">SVGs <a class="header-anchor" href="#svgs" aria-label="Permalink to &quot;SVGs&quot;">​</a></h2><p>You can place <code>.svg</code> files in <code>app/src/front_end/images</code> if you wish to use them in <code>&lt;img&gt;</code> tags. However, if you place svgs in <code>app/src/front_end/svgs</code>, they can be inlined into your HTML via <code>inline_svg</code>. In this case, there is no need for a build step, since the SVG source is included directly in your HTML. This works well for icons.</p><h2 id="favicon-ico" tabindex="-1"><code>favicon.ico</code> <a class="header-anchor" href="#favicon-ico" aria-label="Permalink to &quot;\`favicon.ico\`&quot;">​</a></h2><p><a href="/api/Brut/FrontEnd/Middlewares/Favicon.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Middlewares::Favicon</code></a> is configured by default to handle requests for <code>/favicon.ico</code>. It returns a 301 to <code>/static/images/favicon.ico</code>. This means that Brut expects <code>app/src/front_end/images/favicon.ico</code> to exist.</p><h2 id="all-other-assets" tabindex="-1">All Other Assets <a class="header-anchor" href="#all-other-assets" aria-label="Permalink to &quot;All Other Assets&quot;">​</a></h2><p>Brut currently does not support any other managed asset. However, you can place files in <code>app/public/static</code> and they will be served up directly.</p><h2 id="technical-notes" tabindex="-1">Technical Notes <a class="header-anchor" href="#technical-notes" aria-label="Permalink to &quot;Technical Notes&quot;">​</a></h2><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut&#39;s internals, the source code is always more correct.</p></div><p><em>Last Updated May 7, 2025</em></p><p><code>bin/build-assets</code> manages all of the behavior described on this page. <code>bin/build-assets css</code> and <code>bin/build-assets js</code> modify the file <code>app/config/asset_metadata.json</code>, which stores the mappings between logic paths and hashed paths:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><h2 id="svgs" tabindex="-1">SVGs <a class="header-anchor" href="#svgs" aria-label="Permalink to &quot;SVGs&quot;">​</a></h2><p>You can place <code>.svg</code> files in <code>app/src/front_end/images</code> if you wish to use them in <code>&lt;img&gt;</code> tags. However, if you place svgs in <code>app/src/front_end/svgs</code>, they can be inlined into your HTML via <code>inline_svg</code>, provided by <a href="/api/Brut/FrontEnd/Component/Helpers.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Component::Helpers</code></a> and included in all components and pages. In this case, there is no need for a build step, since the SVG source is included directly in your HTML. This works well for icons.</p><h2 id="favicon-ico" tabindex="-1"><code>favicon.ico</code> <a class="header-anchor" href="#favicon-ico" aria-label="Permalink to &quot;\`favicon.ico\`&quot;">​</a></h2><p><a href="/api/Brut/FrontEnd/Middlewares/Favicon.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Middlewares::Favicon</code></a> is configured by default to handle requests for <code>/favicon.ico</code>. It returns a 301 to <code>/static/images/favicon.ico</code>. This means that Brut expects <code>app/src/front_end/images/favicon.ico</code> to exist.</p><h2 id="all-other-assets" tabindex="-1">All Other Assets <a class="header-anchor" href="#all-other-assets" aria-label="Permalink to &quot;All Other Assets&quot;">​</a></h2><p>Brut currently does not support any other managed asset. However, you can place files in <code>app/public/static</code> and they will be served up directly.</p><h2 id="technical-notes" tabindex="-1">Technical Notes <a class="header-anchor" href="#technical-notes" aria-label="Permalink to &quot;Technical Notes&quot;">​</a></h2><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut&#39;s internals, the source code is always more correct.</p></div><p><em>Last Updated May 7, 2025</em></p><p><code>bin/build-assets</code> manages all of the behavior described on this page. <code>bin/build-assets css</code> and <code>bin/build-assets js</code> modify the file <code>app/config/asset_metadata.json</code>, which stores the mappings between logic paths and hashed paths:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;asset_metadata&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    &quot;.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;/js/app.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/js/app-7MMIZXTZ.js&quot;</span></span>
@@ -16,4 +16,4 @@ import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.1L-BeKqY.js";const u
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">      &quot;/css/styles.css&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/css/styles-ZAISBLGE.css&quot;</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>As you can see, this format could support multiple bundles and additional file types.</p>`,40)]))}const k=e(n,[["render",o]]);export{u as __pageData,k as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>As you can see, this format could support multiple bundles and additional file types.</p>`,39)]))}const k=e(n,[["render",o]]);export{u as __pageData,k as default};

data/docs/assets/{assets.md.D3wunzLx.lean.js → assets.md.7C3HWkga.lean.js}

@@ -1 +1 @@
-import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.1L-BeKqY.js";const u=JSON.parse('{"title":"Assets","description":"","frontmatter":{},"headers":[],"relativePath":"assets.md","filePath":"assets.md"}'),n={name:"assets.md"};function o(h,s,l,r,c,p){return i(),a("div",null,s[0]||(s[0]=[t("",40)]))}const k=e(n,[["render",o]]);export{u as __pageData,k as default};
+import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.1L-BeKqY.js";const u=JSON.parse('{"title":"Assets","description":"","frontmatter":{},"headers":[],"relativePath":"assets.md","filePath":"assets.md"}'),n={name:"assets.md"};function o(h,s,l,r,p,d){return i(),a("div",null,s[0]||(s[0]=[t("",39)]))}const k=e(n,[["render",o]]);export{u as __pageData,k as default};

data/docs/assets/{brut-js.md.o2DAO2s2.js → brut-js.md.B4GYxQVw.js}

@@ -9,4 +9,4 @@ import{_ as t,c as a,o as s,ag as o}from"./chunks/framework.1L-BeKqY.js";const i
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      button { </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Submit&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    end</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  end</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><h3 id="custom-elements" tabindex="-1">Custom Elements <a class="header-anchor" href="#custom-elements" aria-label="Permalink to &quot;Custom Elements&quot;">​</a></h3><p>The JSDoc for these elements&#39; classes should provide complete documentation, however this is an overview of what each one does.</p><table tabindex="0"><thead><tr><th>Element</th><th>Purpose</th></tr></thead><tbody><tr><td><a href="/brut-js/api/AjaxSubmit.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-ajax-submit&gt;</code></a></td><td>Allows submitting a form via Ajax. Handles the use of <code>fetch</code> and all possible cases, but you still provide the logic for what to do with the response.</td></tr><tr><td><a href="/brut-js/api/Autosubmit.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-autosubmit&gt;</code></a></td><td>Auto submits a form when a <code>&lt;select&gt;</code>&#39;s option is chosen.</td></tr><tr><td><a href="/brut-js/api/ConfirmationDialog.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-confirmation-dialog&gt;</code></a></td><td>Enhances a <code>&lt;dialog&gt;</code> to make it easier to use as a generic confirmation with <a href="/brut-js/api/ConfirmSubmit.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-confirm-submit&gt;</code></a></td></tr><tr><td><a href="/brut-js/api/ConfirmSubmit.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-confirm-submit&gt;</code></a></td><td>Uses <code>window.confirm</code> or your owned styled <code>&lt;dialog&gt;</code> to confirm a button click.</td></tr><tr><td><a href="/brut-js/api/ConstraintViolationMessage.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-cv&gt;</code></a></td><td>Like <a href="/brut-js/api/Message.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-message&gt;</code></a> but specific to constraint violations, namely having additional logic for subsituting the field name in the message.</td></tr><tr><td><a href="/brut-js/api/ConstraintViolationMessages.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-cv-messages&gt;</code></a></td><td>Wraps <a href="/brut-js/api/ConstraintViolationMessage.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-cv&gt;</code></a> elements related to a single form input.</td></tr><tr><td><a href="/brut-js/api/CopyToClipboard.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-copy-to-clipboard&gt;</code></a></td><td>Allows the button inside it to copy text from another element onto the clipboard.</td></tr><tr><td><a href="/brut-js/api/Form.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-form&gt;</code></a></td><td>Manages client-side constraint violation UX unified with the server-side, as well as a few quality-of-life improvements for client-side violations and styling. See <a href="/forms.html#forms-and-constraint-violations">Forms</a>.</td></tr><tr><td><a href="/brut-js/api/I18nTranslation.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-i18n-translation&gt;</code></a></td><td>Holds the translated value for a single key in the web site visitor&#39;s locale.</td></tr><tr><td><a href="/brut-js/api/LocaleDetection.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-locale-detection&gt;</code></a></td><td>Sends an Ajax request to the server with the browser&#39;s reported locale and timezone. See <a href="/space-time-continuum.html#getting-timezone-from-the-browser">space-time continuum</a> for more details.</td></tr><tr><td><a href="/brut-js/api/Message.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-message&gt;</code></a></td><td>Shows a message using an <a href="/i18n.html">i18n</a> key to dynamically pull a localized message for client-side constraint violations.</td></tr><tr><td><a href="/brut-js/api/Tabs.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-tabs&gt;</code></a></td><td>Uses ARIA roles related to a tab control and implements it client-side.</td></tr><tr><td><a href="/brut-js/api/Tracing.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-tracing&gt;</code></a></td><td>Sends observability data back to the server to unify a server-side request with client-side tracing.</td></tr></tbody></table><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>BrutJS&#39;s elements were created only to solve specific issues in the apps Brut was initially used for. It&#39;s hoped that more elements will be added to provide a more feature-complete set of primitives to create client-side enhancements.</p></div><h3 id="creating-your-own-custom-elements" tabindex="-1">Creating Your Own Custom Elements <a class="header-anchor" href="#creating-your-own-custom-elements" aria-label="Permalink to &quot;Creating Your Own Custom Elements&quot;">​</a></h3><p>BrutJS includes a base class, <a href="/brut-js/api/BaseCustomElement.html"><code>BaseCustomElement</code></a>, you can use to create your own custom elements with a bit more help, but not too much.</p><p>The documentation for <code>BaseCustomElement</code> has an example, but here are the features you get (noting that you aren&#39;t abandoning the web platform&#39;s API, merely gaining a few additional quality-of-life improvements):</p><ul><li>The ability to add debugging statements that are disabled via markup, not commenting-out <code>console.log</code></li><li>Per-attribute change callbacks so you don&#39;t have to create <code>attributeChangedCallback</code> as a giant <code>if/else</code> block.</li><li>Default implementations of <code>connectedCallback</code> and <code>attributeChangedCallback</code> that call the template method <code>update</code>, thus allowing your element to centralize its logic in one place, regardless of how a state change was triggered.</li><li>Static <code>define()</code> method that defines your element based on its static <code>tagName</code> field. This allows richer interaction of elements, as you can do e.g. <code>document.querySelector(SomeOtherElement.tagName)</code> and better navigate changes to your code over time.</li></ul><p>If you are familiary with the API for autonomous custom elements, <code>BaseCustomElement</code> doesn&#39;t require learning much more. What you know already will be leveraged.</p><h3 id="removing-brutjs" tabindex="-1">Removing BrutJS <a class="header-anchor" href="#removing-brutjs" aria-label="Permalink to &quot;Removing BrutJS&quot;">​</a></h3><p>To remove BrutJS from your app, modify <code>app/src/front_end/js/index.js</code> to remove the <code>import</code> and call to <code>define()</code>. You can then remove it from your <code>package.json</code>.</p><p><strong>Note</strong> If you remove it like this, several features will not work, including locale detection, client-side observability, and client-side form validation UX.</p><h2 id="recommnded-practices" tabindex="-1">Recommnded Practices <a class="header-anchor" href="#recommnded-practices" aria-label="Permalink to &quot;Recommnded Practices&quot;">​</a></h2><p>Consider this decision tree from Alex Russell&#39;s <a href="https://infrequently.org/2024/11/if-not-react-then-what/" target="_blank" rel="noreferrer">If Not React, Then What?</a>:</p><p><img src="`+i+'" alt="Tree showing an SPA decision"></p><p>This is how Brut wants you to consider your app&#39;s architecture. <em>Many</em> apps do not have long-running sessions where visitors make lots of updates to data. Most so-called &quot;CRUD&quot; apps do not fall into this category. The visitor would be better served by a traditional app with server-side HTML generation and minimal interactivity. Visitors would also be better served with progressively enhanced features instead of massive JS payloads that show white screens on low bandwidth/low performance devices.</p><p>Thus, Brut recommends you design your app to work in a tranditional multi-page app sort of way, then <em>enhance</em> as needed using autonomous custom elements.</p><p>You can, of course, bring in whatever framework you like and use that in the normal way. BrutJS&#39;s custom elements should work with any framework.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>See <a href="/custom-element-tests.html">Testing Custom Elements</a>.</p><h2 id="technical-notes" tabindex="-1">Technical Notes <a class="header-anchor" href="#technical-notes" aria-label="Permalink to &quot;Technical Notes&quot;">​</a></h2><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut&#39;s internals, the source code is always more correct.</p></div><p><em>Last Updated June 15, 2025</em></p><p>None.</p>',32)]))}const g=t(n,[["render",r]]);export{m as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">end</span></span></code></pre></div><h3 id="custom-elements" tabindex="-1">Custom Elements <a class="header-anchor" href="#custom-elements" aria-label="Permalink to &quot;Custom Elements&quot;">​</a></h3><p>The JSDoc for these elements&#39; classes should provide complete documentation, however this is an overview of what each one does.</p><table tabindex="0"><thead><tr><th>Element</th><th>Purpose</th></tr></thead><tbody><tr><td><a href="/brut-js/api/AjaxSubmit.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-ajax-submit&gt;</code></a></td><td>Allows submitting a form via Ajax. Handles the use of <code>fetch</code> and all possible cases, but you still provide the logic for what to do with the response.</td></tr><tr><td><a href="/brut-js/api/Autosubmit.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-autosubmit&gt;</code></a></td><td>Auto submits a form when a <code>&lt;select&gt;</code>&#39;s option is chosen.</td></tr><tr><td><a href="/brut-js/api/ConfirmationDialog.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-confirmation-dialog&gt;</code></a></td><td>Enhances a <code>&lt;dialog&gt;</code> to make it easier to use as a generic confirmation with <a href="/brut-js/api/ConfirmSubmit.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-confirm-submit&gt;</code></a></td></tr><tr><td><a href="/brut-js/api/ConfirmSubmit.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-confirm-submit&gt;</code></a></td><td>Uses <code>window.confirm</code> or your owned styled <code>&lt;dialog&gt;</code> to confirm a button click.</td></tr><tr><td><a href="/brut-js/api/ConstraintViolationMessage.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-cv&gt;</code></a></td><td>Like <a href="/brut-js/api/Message.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-message&gt;</code></a> but specific to constraint violations, namely having additional logic for subsituting the field name in the message.</td></tr><tr><td><a href="/brut-js/api/ConstraintViolationMessages.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-cv-messages&gt;</code></a></td><td>Wraps <a href="/brut-js/api/ConstraintViolationMessage.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-cv&gt;</code></a> elements related to a single form input.</td></tr><tr><td><a href="/brut-js/api/CopyToClipboard.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-copy-to-clipboard&gt;</code></a></td><td>Allows the button inside it to copy text from another element onto the clipboard.</td></tr><tr><td><a href="/brut-js/api/Form.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-form&gt;</code></a></td><td>Manages client-side constraint violation UX unified with the server-side, as well as a few quality-of-life improvements for client-side violations and styling. See <a href="/forms.html#forms-and-constraint-violations">Forms</a>.</td></tr><tr><td><a href="/brut-js/api/I18nTranslation.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-i18n-translation&gt;</code></a></td><td>Holds the translated value for a single key in the web site visitor&#39;s locale.</td></tr><tr><td><a href="/brut-js/api/LocaleDetection.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-locale-detection&gt;</code></a></td><td>Sends an Ajax request to the server with the browser&#39;s reported locale and timezone. See <a href="/space-time-continuum.html#getting-timezone-from-the-browser">space-time continuum</a> for more details.</td></tr><tr><td><a href="/brut-js/api/Message.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-message&gt;</code></a></td><td>Shows a message using an <a href="/i18n.html">i18n</a> key to dynamically pull a localized message for client-side constraint violations.</td></tr><tr><td><a href="/brut-js/api/Tabs.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-tabs&gt;</code></a></td><td>Uses ARIA roles related to a tab control and implements it client-side.</td></tr><tr><td><a href="/brut-js/api/Tracing.html" target="_self" rel="noopener" data-no-router><code style="white-space:nowrap;">&lt;brut-tracing&gt;</code></a></td><td>Sends observability data back to the server to unify a server-side request with client-side tracing.</td></tr></tbody></table><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>BrutJS&#39;s elements were created only to solve specific issues in the apps Brut was initially used for. It&#39;s hoped that more elements will be added to provide a more feature-complete set of primitives to create client-side enhancements.</p></div><h3 id="creating-your-own-custom-elements" tabindex="-1">Creating Your Own Custom Elements <a class="header-anchor" href="#creating-your-own-custom-elements" aria-label="Permalink to &quot;Creating Your Own Custom Elements&quot;">​</a></h3><p>BrutJS includes a base class, <a href="/brut-js/api/BaseCustomElement.html"><code>BaseCustomElement</code></a>, you can use to create your own custom elements with a bit more help, but not too much.</p><p>The documentation for <code>BaseCustomElement</code> has an example, but here are the features you get (noting that you aren&#39;t abandoning the web platform&#39;s API, merely gaining a few additional quality-of-life improvements):</p><ul><li>The ability to add debugging statements that are disabled via markup, not commenting-out <code>console.log</code></li><li>Per-attribute change callbacks so you don&#39;t have to create <code>attributeChangedCallback</code> as a giant <code>if/else</code> block.</li><li>Default implementations of <code>connectedCallback</code> and <code>attributeChangedCallback</code> that call the template method <code>update</code>, thus allowing your element to centralize its logic in one place, regardless of how a state change was triggered.</li><li>Static <code>define()</code> method that defines your element based on its static <code>tagName</code> field. This allows richer interaction of elements, as you can do e.g. <code>document.querySelector(SomeOtherElement.tagName)</code> and better navigate changes to your code over time.</li></ul><p>If you are familiar with the API for autonomous custom elements, <code>BaseCustomElement</code> doesn&#39;t require learning much more. What you know already will be leveraged.</p><h3 id="removing-brutjs" tabindex="-1">Removing BrutJS <a class="header-anchor" href="#removing-brutjs" aria-label="Permalink to &quot;Removing BrutJS&quot;">​</a></h3><p>To remove BrutJS from your app, modify <code>app/src/front_end/js/index.js</code> to remove the <code>import</code> and call to <code>define()</code>. You can then remove it from your <code>package.json</code>.</p><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>If you remove it like this, several features will not work, including locale detection, client-side observability, and client-side form validation UX.</p></div><h2 id="recommnded-practices" tabindex="-1">Recommnded Practices <a class="header-anchor" href="#recommnded-practices" aria-label="Permalink to &quot;Recommnded Practices&quot;">​</a></h2><h3 id="leaving-brutjs-in-your-app" tabindex="-1">Leaving BrutJS In Your App <a class="header-anchor" href="#leaving-brutjs-in-your-app" aria-label="Permalink to &quot;Leaving BrutJS In Your App&quot;">​</a></h3><p>BrutJS provides useful tools unrelated to single-page apps, or reactivity, or whatever else you might be concerned with in your client-side code. These features can work alongside whatever framework you want to use. Leave them in unless they are causing a specific problem.</p><h3 id="you-probably-don-t-need-a-single-page-app" tabindex="-1">You Probably Don&#39;t Need a Single-Page App <a class="header-anchor" href="#you-probably-don-t-need-a-single-page-app" aria-label="Permalink to &quot;You Probably Don&#39;t Need a Single-Page App&quot;">​</a></h3><p>Consider this decision tree from Alex Russell&#39;s <a href="https://infrequently.org/2024/11/if-not-react-then-what/" target="_blank" rel="noreferrer">If Not React, Then What?</a>:</p><p><img src="`+i+'" alt="Tree showing an SPA decision"></p><p>This is how Brut wants you to consider your app&#39;s architecture. <em>Many</em> apps do not have long-running sessions where visitors make lots of updates to data. Most so-called &quot;CRUD&quot; apps do not fall into this category. The visitor would be better served by a traditional app with server-side HTML generation and minimal interactivity. Visitors would also be better served with progressively enhanced features instead of massive JS payloads that show white screens on low bandwidth/low performance devices.</p><p>Thus, Brut recommends you design your app to work in a tranditional multi-page app sort of way, then <em>enhance</em> as needed using autonomous custom elements.</p><p>You can, of course, bring in whatever framework you like and use that in the normal way. BrutJS&#39;s custom elements should work with any framework.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to &quot;Testing&quot;">​</a></h2><p>See <a href="/custom-element-tests.html">Testing Custom Elements</a>.</p><h2 id="technical-notes" tabindex="-1">Technical Notes <a class="header-anchor" href="#technical-notes" aria-label="Permalink to &quot;Technical Notes&quot;">​</a></h2><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut&#39;s internals, the source code is always more correct.</p></div><p><em>Last Updated June 15, 2025</em></p><p>None.</p>',35)]))}const g=t(n,[["render",r]]);export{m as __pageData,g as default};

data/docs/assets/{brut-js.md.o2DAO2s2.lean.js → brut-js.md.B4GYxQVw.lean.js}

@@ -1 +1 @@
-import{_ as t,c as a,o as s,ag as o}from"./chunks/framework.1L-BeKqY.js";const i="/assets/spa.qejUdp-5.png",m=JSON.parse('{"title":"BrutJS","description":"","frontmatter":{},"headers":[],"relativePath":"brut-js.md","filePath":"brut-js.md"}'),n={name:"brut-js.md"};function r(l,e,d,h,c,p){return s(),a("div",null,e[0]||(e[0]=[o("",32)]))}const g=t(n,[["render",r]]);export{m as __pageData,g as default};
+import{_ as t,c as a,o as s,ag as o}from"./chunks/framework.1L-BeKqY.js";const i="/assets/spa.qejUdp-5.png",m=JSON.parse('{"title":"BrutJS","description":"","frontmatter":{},"headers":[],"relativePath":"brut-js.md","filePath":"brut-js.md"}'),n={name:"brut-js.md"};function r(l,e,d,h,c,p){return s(),a("div",null,e[0]||(e[0]=[o("",35)]))}const g=t(n,[["render",r]]);export{m as __pageData,g as default};