brut 0.0.29 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b77e4a2a30122b1805ecf5cb52a5313bb137c188364a6baac62270918cd1640
-  data.tar.gz: 393ad694666d889d5672fb592e7f188e19f78f519f19fbd4a5edb1af32ef5d21
+  metadata.gz: 6dad66a7dffc78b032c11605c85ad58139b151316d46ebc0c232dfa91cf76412
+  data.tar.gz: 1dc1a82264b6e3c026aceaf817ad5e4ca6b5b308013861bd38ce185186fbbd1f
 SHA512:
-  metadata.gz: 769c54918d2cb9a3e40e007d954c70ef6ec4033bb1a159d616cc4680aaf5b5d650e0335d729a5acc10b0d9f96574c4dfe5ec5f563bbd82828c6878ea4a532338
-  data.tar.gz: 510b4299c42f476f61110382afdb26c1c71ae8f6aecf16f95bebcf30bb5ac14b0817b08bb0787e3b9b541be59add9e35d4d60df78debbe0627b371aa4639ce00
+  metadata.gz: 3b0397fc6583b5ed0f85507c0d3605cc65cb3f11bf29f04ec5bf366d930ef905195c254b07413f6ded4b4ff229ad5fad47619730d02f88de632b7ea9f405d81a
+  data.tar.gz: c998ae7f7e8fd97ac5b340c35fa027dd3e86ee284ce6868243ea39c333197b8f44ca685fd1af97a56d92c3cf4c87f9a54cdfbf888682b1f86cc9c69b3689e1e5

data/Gemfile.lock

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

data/README.md

@@ -3,6 +3,8 @@
 Brut is a way to make web apps with Ruby, captializing on the knowledge you have—HTTP, HTML, CSS, JavaScript, SQL—without requiring
 *too* much extra stuff to learn.
 
+![Brut Logo in the style of the Washington DC Metro.  It has the metro brown background with all text in white Helvetica.  Centered at the top is "BrutRB". Below that, in the style of metro stops is "Ruby", next to a red dot with "RB" in it, "HTML/CSS/JS" next to an orange dot with "WP" in it, "Phlex" next to a blue dot with "PL" in it, and "RSpec" next to a green dot with "RS" in it.](brutrb.com/images/LogoStop.png)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -19,6 +21,26 @@ Or install it yourself as:
 
     $ gem install brut
 
+## Getting Started
+
+[Please note there is extensive documentation](https://brutrb.com), however to get started, you can use [mkbrut](https://github.com/thirdtank/mkrbut):
+
+```
+docker run --pull always \
+           -v "$PWD":"$PWD" \
+           -w "$PWD" 
+           -it \
+           thirdtank/mkbrut \
+           mkbrut your-new-app
+```
+
+If you have Ruby 3.4 installed somewhere, you can use this via RubyGems as well:
+
+```
+> gem install mkbrut
+> mkbrut your-new-app
+```
+
 ## Developing
 
 The dev environment is managed by Docker and you are encouraged to use this. It's set up so you can edit your code on your computer
@@ -45,6 +67,5 @@ with your editor, but all commands are run inside Docker, which should be more c
 
         dx/exec bin/setup --no-credentials
 
-   The `--no-credentials` means that you will not be able to push to GitHub or RubyGems from within the Docker container. This
-   ability is only needed by maintainers to push new versions of the gem. You can push to GitHub from your computer.
+   The `--no-credentials` means that you will not be able to push to GitHub or RubyGems from within the Docker container. This ability is only needed by maintainers to push new versions of the gem. You can push to GitHub from your computer.
 

data/brutrb.com/.vitepress/config.mjs

@@ -6,6 +6,33 @@ import jsdocLinker from './plugins/jsdocLinker'
 export default defineConfig({
   title: "Brut RB",
   description: "Documentation for the Brut.RB web framework.",
+  head: [
+    ["link", { rel: "icon", href: "/favicon.ico" }],
+    [
+      "meta", {
+        property: "og:title",
+        content: "BrutRB Documentation"
+      }
+    ],
+    [
+      "meta", {
+        property: "og:type",
+        content: "website"
+      }
+    ],
+    [
+      "meta", {
+        property: "og:image",
+        content: "https://brutrb.com/SocialImage.png"
+      }
+    ],
+    ["script", {
+      defer: "",
+      "data-domain": "brutrb.com",
+      src: "https://plausible.io/js/script.js"
+    }
+    ],
+  ],
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
     search: {
@@ -27,10 +54,11 @@ export default defineConfig({
         items: [
           { text: "Getting Started", link: "/getting-started" },
           { text: "Concepts", link: "/overview" },
-          { text: "Documentation Conventions", link: "/doc-conventions" },
-          { text: "Tutorial", link: "/tutorial" },
+          { text: "Features", link: "/features" },
+          { text: "Directory Structure", link: "/dir-structure" },
           { text: "Dev Environment", link: "/dev-environment" },
-          { text: "AI Declaration", link: "/ai" },
+          { text: "Tutorial", link: "/tutorial" },
+          { text: "Documentation Conventions", link: "/doc-conventions" },
         ]
       },
       {
@@ -41,6 +69,7 @@ export default defineConfig({
           { text: "Pages", link: "/pages" },
           { text: "Layouts", link: "/layouts" },
           { text: "Forms", link: "/forms" },
+          { text: "Form Constraints", link: "/form-constraints" },
           { text: "Handlers and Actions", link: "/handlers" },
           { text: "Components", link: "/components" },
           { text: "Flash and Session", link: "/flash-and-session" },
@@ -98,13 +127,23 @@ export default defineConfig({
         collapsed: true,
         items: [
           { text: "Authentication", link: "/recipes/authentication" },
-          { text: "Form Validations", link: "/recipes/form-validations" },
-          { text: "Database Migrations", link: "/recipes/database-migrations" },
-          { text: "Ajax Form Submission", link: "/recipes/ajax-form" },
-          { text: "Custom Telemetry", link: "/recipes/telemetry" },
-          { text: "CLI App/Task", link: "/recipes/cli-app" },
+          { text: "Alternate Layouts", link: "/recipes/alternate-layouts" },
+          { text: "Blank Layouts", link: "/recipes/blank-layouts" },
+          { text: "Custom Flash Class", link: "/recipes/custom-flash" },
+          { text: "Indexed Form Elements", link: "/recipes/indexed-forms" },
+          { text: "Text Field Component", link: "/recipes/text-field-component" },
         ],
-      }
+      },
+      {
+        text: "Meta",
+        collapsed: false,
+        items: [
+          { text: "Why?!", link: "/why" },
+          { text: "ADRs", link: "/adrs" },
+          { text: "Roadmap to 1.0", link: "/roadmap" },
+          { text: "AI Declaration", link: "/ai" },
+        ]
+      },
     ],
 
     socialLinks: [

data/brutrb.com/.vitepress/theme/style.css

@@ -49,46 +49,25 @@
   --vp-c-default-3: var(--vp-c-gray-3);
   --vp-c-default-soft: var(--vp-c-gray-soft);
 
-  --blue-vp-c-brand-1: #0C00A7;
-  --blue-vp-c-brand-2: #6357FF;
-  --blue-vp-c-brand-3: #4C0606;
-  --blue-vp-c-brand-soft: #FFF9F9;
-
-  --vp-c-brand-1: #362400;
-  --vp-c-brand-2: #F1A100;
-  --vp-c-brand-3: #281B00;
-  --vp-c-brand-soft: #FFF1D6;
-
-
-  --xvp-c-brand-1: var(--vp-c-indigo-1);
-  --xvp-c-brand-2: var(--vp-c-indigo-2);
-  --xvp-c-brand-3: var(--vp-c-indigo-3);
-  --xvp-c-brand-soft: var(--vp-c-indigo-soft);
+  --vp-c-brand-1: var(--vp-c-indigo-1);
+  --vp-c-brand-2: var(--vp-c-indigo-2);
+  --vp-c-brand-3: var(--vp-c-indigo-3);
+  --vp-c-brand-soft: var(--vp-c-indigo-soft);
 
   --vp-c-tip-1: var(--vp-c-brand-1);
   --vp-c-tip-2: var(--vp-c-brand-2);
   --vp-c-tip-3: var(--vp-c-brand-3);
   --vp-c-tip-soft: var(--vp-c-brand-soft);
 
-  --xvp-c-warning-1: var(--vp-c-yellow-1);
-  --xvp-c-warning-2: var(--vp-c-yellow-2);
-  --xvp-c-warning-3: var(--vp-c-yellow-3);
-  --xvp-c-warning-soft: var(--vp-c-yellow-soft);
-
-  --vp-c-warning-1: #9E5601;
-  --vp-c-warning-2: #FDAF53;
-  --vp-c-warning-3: #5E3301;
-  --vp-c-warning-soft: #FFF3E5;
-
-  --vp-c-danger-1: #AC0E0E;
-  --vp-c-danger-2: #F14E4E;
-  --vp-c-danger-3: #4C0606;
-  --vp-c-danger-soft: #FFF9F9;
-
-  --xvp-c-danger-1: var(--vp-c-red-1);
-  --xvp-c-danger-2: var(--vp-c-red-2);
-  --xvp-c-danger-3: var(--vp-c-red-3);
-  --xvp-c-danger-soft: var(--vp-c-red-soft);
+  --vp-c-warning-1: var(--vp-c-yellow-1);
+  --vp-c-warning-2: var(--vp-c-yellow-2);
+  --vp-c-warning-3: var(--vp-c-yellow-3);
+  --vp-c-warning-soft: var(--vp-c-yellow-soft);
+
+  --vp-c-danger-1: var(--vp-c-red-1);
+  --vp-c-danger-2: var(--vp-c-red-2);
+  --vp-c-danger-3: var(--vp-c-red-3);
+  --vp-c-danger-soft: var(--vp-c-red-soft);
 }
 
 /**
@@ -121,7 +100,7 @@
 
   --vp-home-hero-image-background-image: linear-gradient(
     -45deg,
-    #ffe7e5,
+    #ffe7e5 30%,
     #a70c00
   );
   --vp-home-hero-image-filter: blur(44px);

data/brutrb.com/adrs.md

@@ -0,0 +1,15 @@
+# Architecture Decision Records
+
+The decisions here aren't *all* the architectural decisions I made, but are some of
+them, and mostly hold up.
+
+`adrs.cloud` is a Brut app.
+
+* [Rely on Web Standards and MDN Baseline](https://adrs.cloud/shared_adrs/padr_b6920f0df907886b8a9207e9e2c9c2a2)
+* [The Core Abstraction is the Plain Old Class](https://adrs.cloud/shared_adrs/padr_57f2397009a8aaf2c6083813ca588d73)
+* [Pages and Forms are First-Class Abstractions…not REST](https://adrs.cloud/shared_adrs/padr_cdfcbe6b116b80a4f3d53fb3a6ed44b2)
+* [Sequel will provide the data layer and its models will only model the database](https://adrs.cloud/shared_adrs/padr_01810ba90a92ec6c081a81affe212fb2)
+* [There will be no controllers. Purpose-built classes will support pages, forms, and components.](https://adrs.cloud/shared_adrs/padr_f318e74925cb3e9d7e0eda329d085c4a)
+* [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)

data/brutrb.com/ai.md

@@ -52,22 +52,17 @@ documentation, is produced by a machine, although spelling and grammar correctio
 
 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.
 
-## Logo
+## Logos
 
-The logo is level 4 - ChatGPT created it. I'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'm
-willing to pay a real person.
+While the various logos look like someone typed "make me a logo in the style of the Washington, DC Metro", 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.
 
-## AI Completions Should Be Viewed with Skepticism
+As such, these are all Level 1.
 
-Due to how LLMs work, there is naturally nothing in any model about Brut.  Anything an
-existing model tells you about Brut is **100% untrustworthy**.  We hope to allow LLMs to consume Brut's
-code, documentation, and examples, so it can be an additional source of help, but currently that is not
-the case.
+## AI Information about Brut Should Be Viewed with Skepticism
 
-**Do not ask an LLM about Brut** until this part of the documentation changes.
-
-For completion-based AI suggestions, **view them with skepticism**.  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.
+* **Answers from an LLM about Brut are likely incorrect.** LLMs will certainly not
+have been trained on information about Brut, since it is new.
+* **Code Completions of Brut Code are suspect.** 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. **Review all Code
+Completions Carefully**.

data/brutrb.com/assets.md

@@ -46,14 +46,7 @@ JavaScript is on line 1 of `app.js`.  This is not helpful for diagnosing issues.
 *SourceMaps* 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.
 
-There are many ways to create source maps and if you've used a tool like WebPack, you'll recall that many of them
-don't produce usable source maps.  Brut uses esbuild'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's accurate.
-
-The tradeoff is that it can take longer to produce than producing an inaccurate one. I'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.
-
+Brut's configuration of esbuild is to produce sourcemaps.
 
 ## Fonts
 
@@ -93,7 +86,7 @@ end
 ## SVGs
 
 You can place `.svg` files in `app/src/front_end/images` if you wish to use them in `<img>` tags.  However, if
-you place svgs in `app/src/front_end/svgs`, they can be inlined into your HTML via `inline_svg`.  In this case,
+you place svgs in `app/src/front_end/svgs`, they can be inlined into your HTML via `inline_svg`, provided by `Brut::FrontEnd::Component::Helpers` 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.
 

data/brutrb.com/brut-js.md

@@ -73,7 +73,7 @@ improvements):
 * Default implementations of `connectedCallback` and `attributeChangedCallback` that call the template method `update`, thus allowing your element to centralize its logic in one place, regardless of how a state change was triggered.
 * Static `define()` method that defines your element based on its static `tagName` field. This allows richer interaction of elements, as you can do e.g. `document.querySelector(SomeOtherElement.tagName)`  and better navigate changes to your code over time.
 
-If you are familiary with the API for autonomous custom elements, `BaseCustomElement` doesn't require
+If you are familiar with the API for autonomous custom elements, `BaseCustomElement` doesn't require
 learning much more.  What you know already will be leveraged.
 
 ### Removing BrutJS
@@ -81,10 +81,20 @@ learning much more.  What you know already will be leveraged.
 To remove BrutJS from your app, modify `app/src/front_end/js/index.js` to remove the `import` and call to
 `define()`.  You can then remove it from your `package.json`.
 
-**Note** If you remove it like this, several features will not work, including locale detection, client-side observability, and client-side form validation UX.
+> [!NOTE]
+> If you remove it like this, several features will not work, including locale detection, client-side observability, and client-side form validation UX.
 
 ## Recommnded Practices
 
+### Leaving BrutJS In Your App
+
+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.
+
+### You Probably Don't Need a Single-Page App
+
 Consider this decision tree from Alex Russell's [If Not React, Then
 What?](https://infrequently.org/2024/11/if-not-react-then-what/):
 

data/brutrb.com/cli.md

@@ -117,7 +117,7 @@ All of this means that the bulk of CLI-specific code you will write is specifyin
 
 Every CLI app is a class that extends `Brut::CLI::App`. This class should contain one inner class for each subcommand. Those classes should extend `Brut::CLI::App`.
 
-Inside your `Brut::CLI::App` class, you can call a few class methods to declare aspects of the UI. In particular, `opts` returns the `OptionParser` in play that you can use to declare global options.  Unlike `OptionParser`'s `on` method, Brut's does not require providing a block. Brut will store the runtime options in a hash (see below).
+Inside your `Brut::CLI::App` class, you can call a few class methods to declare aspects of the UI. In particular, `opts` returns the `OptionParser` in play that you can use to declare global options.  Unlike `OptionParser`'s `on` method, Brut's does not require providing a block. Brut will store the runtime options in an object (see below).
 
 ```ruby
 class MyAppCLI < Brut::CLI::App
@@ -132,7 +132,7 @@ This code means your app's global options are `--dry-run`, which will not accept
 
 Declaring subcommands provides a similar API.  Let's say our app has a "status" subcommand, and a "run" subcommand.
 
-```ruby
+```ruby {7-11,13-16}
 class MyAppCLI < Brut::CLI::App
   description "My awesome command line app"
 
@@ -189,7 +189,7 @@ end
 
 ### Implementing `execute`
 
-Once `execute` is called, your app's internals will have been setup and bootstrapped. That means all you data models can access the database, and any other setup will have ocurred. Generally, `execute` can then have whatever code makes sense.
+Once `execute` is called, your app's internals will have been setup and bootstrapped. That means all your data models can access the database, and any other setup will have ocurred. Generally, `execute` can then have whatever code makes sense.
 
 That said, `execute` has access to a few values to understand the command line invocation and to support testing.
 
@@ -220,23 +220,19 @@ use that affect its behavior.
 
 Currently, Brut doesn't provide a way to create this file, but it's relatively straightforward.  It's almost entirely boilerplate except for your class:
 
-```ruby {14}
+```ruby {9}
 #!/usr/bin/env ruby
 
 require "bundler"
 Bundler.require
 require "pathname"
-
-require "brut/cli"
-
-APP_PATH = File.join(File.dirname($0),"..","app","src")
-$: << APP_PATH
-require "cli/my_app"
+require "brut/cli/apps/db"
 
 exit Brut::CLI.app(
-  MyAppCLI,
-  project_root: Pathname($0).dirname / ".."
-)
+      Brut::CLI::Apps::DB,
+      project_root: Pathname($0).dirname / ".."
+     )
+
 ```
 
 ## Testing