brut 0.1.0 → 0.2.0

data/docs/assets/index.md.Bn9e0sRJ.js

@@ -0,0 +1 @@
+import{_ as a,c as o,o as n,j as t}from"./chunks/framework.1L-BeKqY.js";const s="/assets/LogoStop.Gb3tDhL1.png",g=JSON.parse(`{"title":"","description":"","frontmatter":{"layout":"home","hero":{"name":"Brut RB","text":"Raw Ruby Web Apps","tagline":"Standards-based, No-nonsense, HTML-first, Low Ceremony","ximage":{"src":"/images/LogoTall.png","alt":"A Ruby gemstone embedded into a concrete, brutalist building"},"actions":[{"theme":"brand","text":"Getting Started","link":"/getting-started"},{"theme":"alt","text":"Conceptual Overview","link":"/overview"}]},"xfeatures":[{"title":"Standards-Based","icon":"📄","details":"Brut leverages HTML, HTTP, SQL, and the Ruby standard library to let you write apps using standards you already know…or could quickly learn"},{"title":"Convention-Oriented","icon":"🎚️","details":"In a Brut app, there's usually just one way to do something. Learn things once, and you won't forget how your app works."},{"title":"Objects and Methods","icon":"💻","details":"Author classes to create objects on which to call methods. Nothing fancy."},{"title":"Builds on Community Libraries","icon":"🏘️","details":"Sequel, Phlex, I18n, RSpec. They do it best"}]},"headers":[],"relativePath":"index.md","filePath":"index.md"}`),i={name:"index.md"};function r(d,e,l,c,u,p){return n(),o("div",null,e[0]||(e[0]=[t("p",null,[t("img",{src:s,alt:"logo"})],-1)]))}const h=a(i,[["render",r]]);export{g as __pageData,h as default};

data/docs/assets/index.md.Bn9e0sRJ.lean.js

@@ -0,0 +1 @@
+import{_ as a,c as o,o as n,j as t}from"./chunks/framework.1L-BeKqY.js";const s="/assets/LogoStop.Gb3tDhL1.png",g=JSON.parse(`{"title":"","description":"","frontmatter":{"layout":"home","hero":{"name":"Brut RB","text":"Raw Ruby Web Apps","tagline":"Standards-based, No-nonsense, HTML-first, Low Ceremony","ximage":{"src":"/images/LogoTall.png","alt":"A Ruby gemstone embedded into a concrete, brutalist building"},"actions":[{"theme":"brand","text":"Getting Started","link":"/getting-started"},{"theme":"alt","text":"Conceptual Overview","link":"/overview"}]},"xfeatures":[{"title":"Standards-Based","icon":"📄","details":"Brut leverages HTML, HTTP, SQL, and the Ruby standard library to let you write apps using standards you already know…or could quickly learn"},{"title":"Convention-Oriented","icon":"🎚️","details":"In a Brut app, there's usually just one way to do something. Learn things once, and you won't forget how your app works."},{"title":"Objects and Methods","icon":"💻","details":"Author classes to create objects on which to call methods. Nothing fancy."},{"title":"Builds on Community Libraries","icon":"🏘️","details":"Sequel, Phlex, I18n, RSpec. They do it best"}]},"headers":[],"relativePath":"index.md","filePath":"index.md"}`),i={name:"index.md"};function r(d,e,l,c,u,p){return n(),o("div",null,e[0]||(e[0]=[t("p",null,[t("img",{src:s,alt:"logo"})],-1)]))}const h=a(i,[["render",r]]);export{g as __pageData,h as default};

data/docs/assets/{overview.md.Bdq4qt3L.js → overview.md.iMnwLO4x.js}

@@ -1 +1 @@
-import{_ as t,c as a,o as r,ag as s}from"./chunks/framework.1L-BeKqY.js";const o="/assets/OverviewMetro.DUS-5fUZ.png",g=JSON.parse('{"title":"Conceptual Overview","description":"","frontmatter":{},"headers":[],"relativePath":"overview.md","filePath":"overview.md"}'),i={name:"overview.md"};function n(l,e,c,d,h,u){return r(),a("div",null,e[0]||(e[0]=[s('<h1 id="conceptual-overview" tabindex="-1">Conceptual Overview <a class="header-anchor" href="#conceptual-overview" aria-label="Permalink to &quot;Conceptual Overview&quot;">​</a></h1><p>Brut is a way to build web apps that generate HTML, have JavaScript and CSS, and interact with a Database. It&#39;s built on Ruby standard libraries and community libraries like <a href="https://sequel.jeremyevans.net/" target="_blank" rel="noreferrer">Sequel</a> and <a href="https://phlex.fun" target="_blank" rel="noreferrer">Phlex</a>.</p><p>Brut&#39;s approach and design are built on three core values:</p><ul><li><strong>Leverage Standards</strong> - The web platform is great, and Brut wants you to use it.</li><li><strong>There&#39;s One Best Way To Do It</strong> - Flexibility leads to chaos.</li><li><strong>Simple over Easy</strong> - Verbose code that can be quickly understood beats impenetrable compact DSLs every day.</li></ul><p>Brut&#39;s abstractions tend to mirror concepts found in the domain of web sites. For example, a browser serves up a web page at a URL. In Brut, that&#39;s called a <em>page</em> and you&#39;d create a subclass of <a href="/api/Brut/FrontEnd/Page.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Page</code></a> to implement it.</p><p>Brut tries to avoid abstractions that simply translate existing standards into a more aestheticly pleasing form. You already need to know CSS, HTML, the Web Platform, and SQL, so there&#39;s little to gain by requiring you to learn a different way to use them.</p><h2 id="basic-elements" tabindex="-1">Basic Elements <a class="header-anchor" href="#basic-elements" aria-label="Permalink to &quot;Basic Elements&quot;">​</a></h2><p>Brut organizes its code and behavior around four basic concepts:</p><ul><li><strong>Client</strong> or <em>Client Side</em> is the web browser (or HTTP client). This is where CSS is applied to HTML and where JavaScript is executed. HTTP requests are initiated here.</li><li><strong>Server</strong> or <em>Server Side</em> is where any code not in the browser runs. In Brut, this includes HTML generation, SQL queries, and everything in between.</li><li><strong>Front End</strong> is the code that deals with producing your user interface or HTTP API. A lot of this code runs on the <em>server side</em>, however it exists to provide a user interface of some sort.</li><li><strong>Back End</strong> is the code that deals with everything else, such as accessing a database, executing business logic, or managing background jobs.</li></ul><p><img src="'+o+'" alt="Architectural Overview"></p><ul><li><strong>Visitor</strong> is someone visiting your web site or app.</li><li><strong>Browser</strong> is, well, a web browser</li><li><a href="/pages.html"><strong>Pages</strong></a> generate web pages, which is what happens when a browser&#39;s UI navigates to a URL.</li><li><a href="/forms.html"><strong>Forms</strong></a> are submitted by the browser to the server. In Brut, a form describes the contents of a <code>&lt;form&gt;</code> as well as provides access to the submitted data.</li><li><a href="/handlers.html"><strong>Handlers</strong></a> receive non-GET HTTP requests from the browser, notably form submissions.</li><li><a href="/components.html"><strong>Components</strong></a> generate HTML fragments and are used to generate the HTML of a page or for re-use across pages.</li><li><a href="/javascript.html"><strong>JavaScript</strong></a> and <a href="/assets.html"><strong>Assets</strong></a> (including <a href="/css.html">CSS</a>) are bundled on the server and sent to the client.</li><li><a href="/business-logic.html"><strong>Domain Logic</strong></a> as where your business and domain logic lives and can be implemented however you like.</li><li><a href="/database-access.html"><strong>DB Models</strong></a> are objects that provide access to your database.</li><li><strong>Relational Database</strong> is your database, where data is stored.</li></ul><p>Brut doesn&#39;t prevent the addition of more pieces of infrastructure or code. You can add a Redis cache, a Sidekiq job backend, or integrate with third party APIs.</p><h2 id="brut-is-not-mvc" tabindex="-1">Brut is Not MVC <a class="header-anchor" href="#brut-is-not-mvc" aria-label="Permalink to &quot;Brut is Not MVC&quot;">​</a></h2><p>Brut is <em>not</em> an MVC framework, nor does it use the concept of <em>resources</em> as an abstraction. Although HTTP does include this concept, we find it&#39;s not as useful for managing web apps as it may seem.</p><p>We&#39;ve found that teams often struggle with mapping what everyone else calls pages to resources and HTTP verbs. We also find that the consonance features, resources, actions, and database tables never materializes. We&#39;re basically not going to debate what the meaning of the <code>DELETE</code> verb on the <code>widgets</code> resource is actually supposed to mean.</p><h2 id="brut-is-hippocratic-licensed" tabindex="-1">Brut is Hippocratic Licensed <a class="header-anchor" href="#brut-is-hippocratic-licensed" aria-label="Permalink to &quot;Brut is Hippocratic Licensed&quot;">​</a></h2><p>It&#39;s important to me that Brut is used to make the world a better place. Please take a not of <a href="https://firstdonoharm.dev/version/3/0/cl-eco-media-my-tal-xuar.txt" target="_blank" rel="noreferrer">its license</a></p>',17)]))}const m=t(i,[["render",n]]);export{g as __pageData,m as default};
+import{_ as t,c as a,o as r,ag as s}from"./chunks/framework.1L-BeKqY.js";const o="/assets/OverviewMetro.DUS-5fUZ.png",g=JSON.parse('{"title":"Conceptual Overview","description":"","frontmatter":{},"headers":[],"relativePath":"overview.md","filePath":"overview.md"}'),i={name:"overview.md"};function n(l,e,c,d,h,u){return r(),a("div",null,e[0]||(e[0]=[s('<h1 id="conceptual-overview" tabindex="-1">Conceptual Overview <a class="header-anchor" href="#conceptual-overview" aria-label="Permalink to &quot;Conceptual Overview&quot;">​</a></h1><p>Brut is a way to build web apps that generate HTML, have JavaScript and CSS, and interact with a Database. It&#39;s built on Ruby standard libraries and community libraries like <a href="https://sequel.jeremyevans.net/" target="_blank" rel="noreferrer">Sequel</a> and <a href="https://phlex.fun" target="_blank" rel="noreferrer">Phlex</a>.</p><p>Brut&#39;s approach and design are built on three core values:</p><ul><li><strong>Leverage Standards</strong> - The web platform is great, and Brut wants you to use it.</li><li><strong>There&#39;s One Best Way To Do It</strong> - Flexibility leads to chaos.</li><li><strong>Simple over Easy</strong> - Verbose code that can be quickly understood beats impenetrable compact DSLs every day.</li></ul><p>Brut&#39;s abstractions tend to mirror concepts found in the domain of web sites. For example, a browser serves up a web page at a URL. In Brut, that&#39;s called a <em>page</em> and you&#39;d create a subclass of <a href="/api/Brut/FrontEnd/Page.html" target="_self" rel="noopener" data-no-router><code>Brut::FrontEnd::Page</code></a> to implement it.</p><p>Brut tries to avoid abstractions that simply translate existing standards into a more aestheticly pleasing form. You already need to know CSS, HTML, the Web Platform, and SQL, so there&#39;s little to gain by requiring you to learn a different way to use them.</p><h2 id="basic-elements" tabindex="-1">Basic Elements <a class="header-anchor" href="#basic-elements" aria-label="Permalink to &quot;Basic Elements&quot;">​</a></h2><p>Brut organizes its code and behavior around four basic concepts:</p><ul><li><strong>Client</strong> or <em>Client Side</em> is the web browser (or HTTP client). This is where CSS is applied to HTML and where JavaScript is executed. HTTP requests are initiated here.</li><li><strong>Server</strong> or <em>Server Side</em> is where any code not in the browser runs. In Brut, this includes HTML generation, SQL queries, and everything in between.</li><li><strong>Front End</strong> is the code that deals with producing your user interface or HTTP API. A lot of this code runs on the <em>server side</em>, however it exists to provide a user interface of some sort.</li><li><strong>Back End</strong> is the code that deals with everything else, such as accessing a database, executing business logic, or managing background jobs.</li></ul><p><img src="'+o+'" alt="Architectural Overview"></p><ul><li><strong>Visitor</strong> is someone visiting your web site or app.</li><li><strong>Browser</strong> is, well, a web browser</li><li><a href="/pages.html"><strong>Pages</strong></a> generate web pages, which is what happens when a browser&#39;s UI navigates to a URL.</li><li><a href="/forms.html"><strong>Forms</strong></a> are submitted by the browser to the server. In Brut, a form describes the contents of a <code>&lt;form&gt;</code> as well as provides access to the submitted data.</li><li><a href="/handlers.html"><strong>Handlers</strong></a> receive non-GET HTTP requests from the browser, notably form submissions.</li><li><a href="/components.html"><strong>Components</strong></a> generate HTML fragments and are used to generate the HTML of a page or for re-use across pages.</li><li><a href="/javascript.html"><strong>JavaScript</strong></a> and <a href="/assets.html"><strong>Assets</strong></a> (including <a href="/css.html">CSS</a>) are bundled on the server and sent to the client.</li><li><a href="/business-logic.html"><strong>Domain Logic</strong></a> as where your business and domain logic lives and can be implemented however you like.</li><li><a href="/database-access.html"><strong>DB Models</strong></a> are objects that provide access to your database.</li><li><strong>Relational Database</strong> is your database, where data is stored.</li></ul><p>Brut doesn&#39;t prevent the addition of more pieces of infrastructure or code. You can add a Redis cache, a Sidekiq job backend, or integrate with third party APIs.</p><h2 id="brut-is-not-mvc" tabindex="-1">Brut is Not MVC <a class="header-anchor" href="#brut-is-not-mvc" aria-label="Permalink to &quot;Brut is Not MVC&quot;">​</a></h2><p>Brut is <em>not</em> an MVC framework, nor does it use the concept of <em>resources</em> as an abstraction. Although HTTP does include this concept, we find it&#39;s not as useful for managing web apps as it may seem.</p><p>We&#39;ve found that teams often struggle with mapping what everyone else calls pages to resources and HTTP verbs. We also find that the consonance of features, resources, actions, and database tables never materializes. We&#39;re basically not going to debate what the meaning of the <code>DELETE</code> verb on the <code>widgets</code> resource is actually supposed to mean.</p><h2 id="brut-is-hippocratic-licensed" tabindex="-1">Brut is Hippocratic Licensed <a class="header-anchor" href="#brut-is-hippocratic-licensed" aria-label="Permalink to &quot;Brut is Hippocratic Licensed&quot;">​</a></h2><p>It&#39;s important to me that Brut is used to make the world a better place. Please take a note of <a href="https://firstdonoharm.dev/version/3/0/cl-eco-media-my-tal-xuar.txt" target="_blank" rel="noreferrer">its license</a></p>',17)]))}const m=t(i,[["render",n]]);export{g as __pageData,m as default};

data/docs/assets/roadmap.md.C6PRi0DX.js

@@ -0,0 +1 @@
+import{_ as t,c as o,o as a,ag as i}from"./chunks/framework.1L-BeKqY.js";const h=JSON.parse('{"title":"Roadmap to 1.0","description":"","frontmatter":{},"headers":[],"relativePath":"roadmap.md","filePath":"roadmap.md"}'),l={name:"roadmap.md"};function r(s,e,n,d,c,m){return a(),o("div",null,e[0]||(e[0]=[i('<h1 id="roadmap-to-1-0" tabindex="-1">Roadmap to 1.0 <a class="header-anchor" href="#roadmap-to-1-0" aria-label="Permalink to &quot;Roadmap to 1.0&quot;">​</a></h1><p>A lot of Brut is solid, but there&#39;s several things missing from what I would call a 1.0 release. Here are some ideas of what I think is needed:</p><h2 id="better-dev-experience" tabindex="-1">Better Dev Experience <a class="header-anchor" href="#better-dev-experience" aria-label="Permalink to &quot;Better Dev Experience&quot;">​</a></h2><ul><li>The output of <code>bin/dev</code> isn&#39;t great.</li><li>otel-desktop-viewer is cool, but not the easiest to figure out issues as compred to good &#39;ole logging.</li><li>Error pages in the app are <em>really</em> bad.</li><li>CLI apps are OK, but could be fancier.</li></ul><h2 id="more-tests" tabindex="-1">More Tests <a class="header-anchor" href="#more-tests" aria-label="Permalink to &quot;More Tests&quot;">​</a></h2><ul><li>Unit tests for all/most classes are needed. There&#39;s only a few now.</li><li>Integration test of <code>mkbrut</code>, all automated.</li><li>Web component/custom element tests need to be re-thought.</li><li>Test output is a wall of text stack trace and this sucks.</li><li>Improvements in access to Playwright features.</li><li>Playright is the worst E2E testing tool except all the rest. Would love a better option here.</li></ul><h2 id="more-complete-web-features" tabindex="-1">More Complete Web Features <a class="header-anchor" href="#more-complete-web-features" aria-label="Permalink to &quot;More Complete Web Features&quot;">​</a></h2><ul><li>Content security policy doens&#39;t allow for hashes, which can be limiting in some situations. I want everyone to be running with a CSP, so it has to be configurable to some degree.</li><li>Websockets, server-push, etc. should be possible or at least have a recipe.</li><li>Learn more about importmaps.</li></ul><h2 id="client-side-improvements" tabindex="-1">Client-Side Improvements <a class="header-anchor" href="#client-side-improvements" aria-label="Permalink to &quot;Client-Side Improvements&quot;">​</a></h2><p>BrutJS is woefully incomplete. I&#39;d like developers to be able to accomplishe certain tasks without needing a framework:</p><ul><li>Hooks into asset building to e.g. enable TailwindCSS or other tools.</li><li>Better use of <code>fetch</code> in more situations</li><li>Server-generated HTML replacement</li><li>Better support for &quot;API&quot; style back-end when a framework <em>is</em> going to be used.</li></ul><h2 id="deployment" tabindex="-1">Deployment <a class="header-anchor" href="#deployment" aria-label="Permalink to &quot;Deployment&quot;">​</a></h2><p>Out of the box support for more deployment mechanism, at least:</p><ul><li>Normal Heroku/<code>Procfile</code>-based deploy</li><li>Digital Ocean-style hosting</li><li>VPS?</li></ul><h2 id="documentation" tabindex="-1">Documentation <a class="header-anchor" href="#documentation" aria-label="Permalink to &quot;Documentation&quot;">​</a></h2><ul><li>More recipes for how to do things</li><li>More complete API docs with examples</li><li>A unified look and feel across the board</li><li>Get rid of VitePress for something less client-heavy, but still great</li><li>Dash-accessible API docs</li></ul><h2 id="misc" tabindex="-1">Misc <a class="header-anchor" href="#misc" aria-label="Permalink to &quot;Misc&quot;">​</a></h2><ul><li>More direct Sidekiq support</li></ul>',18)]))}const p=t(l,[["render",r]]);export{h as __pageData,p as default};

data/docs/assets/roadmap.md.C6PRi0DX.lean.js

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