brut 0.0.26 → 0.0.27

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 327b83333a37823010e1d2763646d56bd503d505d6c965ddc5d0d8098ecd9299
-  data.tar.gz: d12d8d46f6e459d97f3489218302da647e073ac4d8e48cf57cd1d1fee998c6a1
+  metadata.gz: ad36cf0ea0c628d6ab48dafc53dfb9253f19ac5df73669e86532970ea70e759d
+  data.tar.gz: fa4dcb2b80e205fb2de2372fe8cfdfd441b6634ab69458287e41f5e681cc507f
 SHA512:
-  metadata.gz: a55e3607d5d127e74f93864f6dc19fad6dc2a0631e56559cf92df4b5762771d82d5bc0c5a2d289d6948a0899568e0138e503fea98f91d42007cefb9b3e83482b
-  data.tar.gz: e901897e8d8eb2a2ef08bc4e5efacc0c3a13f6981f8523a2e0db3ade740f648923ecb29e9634ea133dd16efccedeecb0b9ec06f820c0b4d77b7f34068f96d540
+  metadata.gz: a357cccfd1224fcd00d7909670d026a532c1d8cdc0bdd2549a92fad1621370bbdcde707b8fdab0c003ddbe71728018aef2c45201194614025f1b97520775847e
+  data.tar.gz: 042fc9088726c05c0f12b573f54eeb2d7ace79a4552a5756170fb776eaddf5ad895d2a702f1b2e5f05d94f5ff07b7ca4b560e9c3729153441458aa6c3c8e2340

data/Gemfile.lock

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

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

@@ -89,6 +89,7 @@ export default defineConfig({
           { text: "Middleware", link: "/middleware" },
           { text: "Instrumentation", link: "/instrumentation" },
           { text: "Security", link: "/security" },
+          { text: "LSP Support", link: "/lsp" },
         ],
       },
       {

data/brutrb.com/ai.md

@@ -58,7 +58,7 @@ The logo is level 4 - ChatGPT created it. I'd love to have a real person make a
 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.
 
-## AI That Teachs You About Brut Does Not Currently Exist
+## AI Completions Should Be Viewed with Skepticism
 
 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
@@ -66,3 +66,8 @@ code, documentation, and examples, so it can be an additional source of help, bu
 the case.
 
 **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.

data/brutrb.com/components.md

@@ -136,7 +136,7 @@ To use it without having to instantiate it, call `global_component` with the com
 class HomePage < AppPage
   def page_template
     header do
-      render global_component(FlashMessage)
+      global_component(FlashMessage) # note: render not required
     end
   end
 end

data/brutrb.com/forms.md

@@ -87,7 +87,7 @@ class LoginPage < AppPage
 end
 ```
 
-Brut can generate the HTML for the needed inputs via `Brut::FrontEnd::Components::Inputs::TextField.for_form_input`, which is a very long name.  Hold that thought for now. This method will generate an `<input>` element for you, based on how you've set up the field in your form class. The HTML element will have a value set based on the form, if there is a value.
+Brut can generate the HTML for the needed inputs via `Brut::FrontEnd::Components::Inputs::TextField`, which is a very long class name.  Hold that thought for now. This method will generate an `<input>` element for you, based on how you've set up the field in your form class. The HTML element will have a value set based on the form, if there is a value.
 
 ```ruby {11,12}
 # app/src/front_end/pages/login_page.rb
@@ -100,8 +100,8 @@ class LoginPage < AppPage
     form_tag(method: :post,
              action: LoginHandler.routing) do
       # We promise you don't have to type this every time!
-      Brut::FrontEnd::Components::Inputs::TextField.for_form_input(form: @form, input_name: :email)
-      Brut::FrontEnd::Components::Inputs::TextField.for_form_input(form: @form, input_name: :password)
+      Brut::FrontEnd::Components::Inputs::TextField.new(form: @form, input_name: :email)
+      Brut::FrontEnd::Components::Inputs::TextField.new(form: @form, input_name: :password)
       button { "Login" }
     end
   end
@@ -134,7 +134,7 @@ class LoginPage < AppPage
 end
 ```
 
-This allows you to call `Inputs::TextField.for_form_input`:
+This allows you to call `Inputs::TextField` like a method:
 
 ```ruby {12,13}
 # app/src/front_end/pages/login_page.rb
@@ -148,8 +148,8 @@ class LoginPage < AppPage
   def page_template
     form_tag(method: :post,
              action: LoginHandler.routing) do
-      Inputs::TextField.for_form_input(form: @form, input_name: :email)
-      Inputs::TextField.for_form_input(form: @form, input_name: :password)
+      Inputs::TextField(form: @form, input_name: :email)
+      Inputs::TextField(form: @form, input_name: :password)
       button { "Login" }
     end
   end
@@ -217,7 +217,7 @@ with that email and password. Let's assume the existence of the class `Authorize
 If that returns `nil`, we want to re-render the `LoginPage`, exposing some sort of constraint violation message
 so it can be rendered. We also want the form fields to be pre-filled with the values the visitor provided.
 
-`for_form_input` can handle this, so we need to pass our form object into `LoginPage` instead of allowing `LoginPage` to create an empty one.  We can do that by adding a `form:` keyword argument that defaults to `nil`:
+`Brut::FrontEnd::Components` can handle this, so we need to pass our form object into `LoginPage` instead of allowing `LoginPage` to create an empty one.  We can do that by adding a `form:` keyword argument that defaults to `nil`:
 
 ```ruby {3,4}
 # app/src/front_end/pages/login_page.rb
@@ -229,8 +229,8 @@ class LoginPage < AppPage
   def page_template
     form_tag(method: :post,
              action: LoginHandler.routing) do
-      Inputs::TextField.for_form_input(form: @form, input_name: :email)
-      Inputs::TextField.for_form_input(form: @form, input_name: :password)
+      Inputs::TextField(form: @form, input_name: :email)
+      Inputs::TextField(form: @form, input_name: :password)
       button { "Login" }
     end
   end
@@ -267,12 +267,11 @@ class LoginHandler < AppHandler
 end
 ```
 
-When `LoginPage` generates HTML, different HTML is generated, since the form being passed to
-`for_form_input` contains constraint violations.
+When `LoginPage` generates HTML, different HTML is generated, since the form being passed to the components contains constraint violations.
 
 #### Showing Constraint Violations in HTML
 
-When `Inputs::TextField.for_form_input` is called with an existing form that has constraint violations, different HTML is generated.  This is what would be produced by our existing `LoginPage` (again, formatted her for clarity):
+When `Brut::FrontEnd::Components::Inputs::TextField` is created with an existing form that has constraint violations, different HTML is generated.  This is what would be produced by our existing `LoginPage` (again, formatted her for clarity):
 
 ```html {3}
 <form method="post" action="/login">
@@ -335,10 +334,10 @@ def page_template
   form_tag(method: :post,
            action: LoginHandler.routing) do
 
-    Inputs::TextField.for_form_input(form: @form, input_name: :email)
+    Inputs::TextField(form: @form, input_name: :email)
     ConstraintViolations(form: @form, input_name: :email)
 
-    Inputs::TextField.for_form_input(form: @form, input_name: :password)
+    Inputs::TextField(form: @form, input_name: :password)
     ConstraintViolations(form: @form, input_name: :password)
 
     button { "Login" }
@@ -419,10 +418,10 @@ def page_template
     form_tag(method: :post,
              action: LoginHandler.routing) do
 
-      Inputs::TextField.for_form_input(form: @form, input_name: :email)
+      Inputs::TextField(form: @form, input_name: :email)
       ConstraintViolations(form: @form, input_name: :email)
 
-      Inputs::TextField.for_form_input(form: @form, input_name: :password)
+      Inputs::TextField(form: @form, input_name: :password)
       ConstraintViolations(form: @form, input_name: :password)
 
       button { "Login" }
@@ -564,7 +563,7 @@ class LoginForm < AppForm
 end
 ```
 
-Checkboxes can be rendered by `Inputs::TextField.for_form_input`, and their `value` attribute would always be the string `"true"`. If the form's value for the input is the string `"true"`, the checkbox would have the `checked` attribute:
+Checkboxes can be rendered by a `Brut::FrontEnd::Components::Inputs::TextField`, and their `value` attribute would always be the string `"true"`. If the form's value for the input is the string `"true"`, the checkbox would have the `checked` attribute:
 
 ```html
 <!-- Form.new(params: { remember: "true" }) -->
@@ -578,8 +577,7 @@ Radio buttons are implemented in HTML by `<input type="radio">`, with an expecta
 having the same value for the `name` attribute, but different values for the `value` attributes, one of which may
 be `checked`.
 
-Brut implements this via `Brut::FrontEnd::Components::Inputs::RadioButton`, which has the class method
-`for_form_input`.  To create radio buttons in a form, use `radio_button_group`:
+Brut implements this via `Brut::FrontEnd::Components::Inputs::RadioButton`, whose initializer behaves like the other form input components. To create radio buttons in a form, use `radio_button_group`:
 
 ```ruby {5}
 # app/src/front_end/forms/login_form.rb
@@ -598,7 +596,7 @@ def view_template
     [ :never, :one_week, :one_month ].each do |remember|
       label do
         render(
-          Inputs::RadioButton.for_form_input(
+          Inputs::RadioButton(
             form:,
             input_name: :remember,
             value: remember
@@ -643,8 +641,7 @@ class LoginForm < AppForm
 end
 ```
 
-Creating the HTML can be done with `Brut::FrontEnd::Components::Inputs::Select`. It's `for_form_input` is more complex, since it provides a way to show visitor-friendly values instead of the innate `value` for each option,
-  as well as to allow for a "blank" entry.
+Creating the HTML can be done with `Brut::FrontEnd::Components::Inputs::Select`. It's initializer is more complex, since it provides a way to show visitor-friendly values instead of the innate `value` for each option, as well as to allow for a "blank" entry.
 
 Let's suppose we have a class named `LoginRememberOption`. It's a simple wrapper around a value we might store in the database and use to lookup an I18n key.
 
@@ -677,7 +674,7 @@ To show these options in a `<select>`, we might do this:
 def view_template
   form do
     render(
-      Inputs::Select.for_form_input(
+      Inputs::Select(
         form:,
         input_name: :remember,
         options: LoginRememberOption.all,
@@ -718,8 +715,7 @@ end
 
 In this case, we need `required: false` or every single field we generate will be required.
 
-To generate the HTML, use the optional `index:` parameter to `for_form_input` as well as for
-`ConstraintViolations`:
+To generate the HTML, use the optional `index:` parameter to the initializer as well as for `ConstraintViolations`:
 
 ```ruby {11,16}
 # Inside e.g. app/src/front_end/pages/create_bulk_widget_page.rb
@@ -729,7 +725,7 @@ def page_template
              action: BulkWidgetForm.routing) do
 
       10.times do |i|
-        Inputs::TextField.for_form_input(
+        Inputs::TextField(
           form: @form,
           input_name: :name,
           index: i

data/brutrb.com/getting-started.md

@@ -1,46 +1,51 @@
 # Getting Started
 
-To make a new app with Brut, you'll need to clone a template app, initialize it, then set up your dev environment.
+Brut is developed alongside a separate gem called `mkbrut`, which allows you to
+create a new Brut app. It will set up you dev environment as well.
 
-## Clone the App Template
+## Get `mkbrut`
 
-To get started, clone the Brut app template:
+If you have a Ruby 3.4 (or later) environment set up on your computer, you can use 
+RubyGems:
 
 ```
-> git clone https://github.com/thirdtank/brut-app-template your-app-name
+gem install mkbrut
+```
+
+If not, we recommend you use a pre-built Docker image:
+
+```
+docker pull XXXX
 ```
 
 ## Init Your App
 
-The template includes `init`, which will ask you a few questions to get everything set up.
+A Brut app just needs a name, which will be used to derive a few more useful values.
+For now:
 
 ```
-> cd your-app-name
-> ./init
+mkbrut my-new-app
 ```
 
-You'll need to provide four pieces of info:
+This will create your new app, along with some demo routes, components, handlers, and tests. If this is your first time using Brut, we recommend you examine these demo components.  However, if you just want to skip all that:
 
-* Your app's name, suitable has a hostname or identifier
-* A prefix for your app's externalizable ids
-* A prefix for your app's custom elements
-* An organization name, needed for deployment
-
-::: tip
-Choose your app's name wisely, however everything else can be easily changed later, so don't stress!
-:::
+```
+mkbrut --no-demo my-new-app
+```
 
-## Set Up Your Dev Environment
+## Start Your Dev Environment
 
-Brut includes a dev environment based on Docker.
+Brut includes a dev environment based on Docker.  It uses Docker compose to run a
+Docker container where your app will run, a Docker container for Postgres, and a
+Docker container for local observability via OpenTelemetry.
 
 1. [Install Docker](https://docs.docker.com/get-started/get-docker/)
-2. Build Your images
+2. Build the image used to create you app's container:
 
    ```
    > dx/build
    ```
-3. Start up the environment
+3. Start up all the containers:
 
    ```
    > dx/start
@@ -51,6 +56,13 @@ Brut includes a dev environment based on Docker.
    > dx/exec bin/setup
    ```
 
+   OR:
+
+   ```
+   > dx/exec bash
+   inside-container> bin/setup
+   ```
+
 Now, you're ready to go
 
 ## Run the App
@@ -59,8 +71,31 @@ Now, you're ready to go
 > dx/exec bin/dev
 ```
 
+OR
+
+```
+> dx/exec bash
+> bin/dev
+```
+
 You can now visit your app at `localhost:6502`
 
+## Run the Tests
+
+Even without the demo, there are a few components set up, and there are some tests:
+
+```
+> dx/exec bin/ci
+```
+
+OR
+
+```
+> dx/exec bash
+> bin/ci
+```
+
 ## Now Build The Rest of Your App 🦉
 
-You can [follow the tutorial](/tutorial), check out the [conceptual overview](/overview), or dive straight into the API docs.
+You can [follow the tutorial](/tutorial), check out the [conceptual overview](/overview), or dive straight into the API docs.  You might also want to check out the docs for [LSP Support](/lsp).
+

data/brutrb.com/lsp.md

@@ -0,0 +1,23 @@
+# Language Server Protocol (LSP) Support
+
+Because Brut development happens inside Docker, but your editor likely runs on your
+computer, getting LSP servers running takes a few more steps.
+
+## Overview
+
+When you created your app with `mkbrut`, the following LSP-related modules are set
+up and/or installed:
+
+* Shopify's Ruby LSP server (installed from `bin/setup`)
+* Microsoft's TypeScript/JavaScript and CSS LSP serfvers (specified in `package.json`, installed when `npm install` runs from `bin/setup`)
+
+In order to use them from your computer a few configurations are needed, some of
+which Brut has done, and some you will need to do.
+
+| Configuration | Description | Brut Handled? |
+|---|---|---|
+| Paths inside Docker Must Match Your Computer | When an LSP server communicates about a file, it does so with a path. That means that paths inside the Docker container must be the same as those on your computer.  Brut achievecs this by using `${CWD}` inside `docker-compose.dx.yml` | ✅ |
+| Third party libraries must *also* be installed in a path that is the same in both places | When jumping to a definition, the LSP server will again use paths, which must match.  Because Node modules are installed local to your app, they already work.  Ruby Gems, however, are configured to be installed in `local-gems` in your app.  Brut should've added this to `.gitignore` and setup everything inside Docker to use it. | ✅ |
+| Your editor must use `dx/exec` to execute LSP commands | Your editor will need to know that the LSP servers are running inside Docker.  If your editor allows configuring the commands used to do this, you must prefix them with `dx/exec bashc -lc`. See [my blog post](https://naildrivin5.com/blog/2025/06/12/neovim-and-lsp-servers-working-with-docker-based-development.html) for details. | ❌ |
+| Other languages or plugins to existing LSP servers | I haven't used these, so no idea how well they work. | ❌ |
+

data/lib/brut/cli/apps/test.rb

@@ -133,7 +133,8 @@ class Brut::CLI::Apps::Test < Brut::CLI::App
           test_expected: true,
         }
         if pathname.fnmatch?( (Brut.container.components_src_dir / "**").to_s )
-          if pathname.basename.to_s == "app_component.rb"
+          if pathname.basename.to_s == "app_component.rb" || 
+             pathname.basename.to_s == "custom_element_registration.rb"
             hash[:type] = :infrastructure
             hash[:test_expected] = false
           else

data/lib/brut/front_end/component.rb

@@ -1,6 +1,22 @@
 require "phlex"
 
-# Components holds Brut-provided components that are of general use to any web app
+# Namespace for Brut-provided components that are of general use to any web app.
+# Also extends [`Phlex:::Kit`](https://www.phlex.fun/components/kits.html), meaning
+# you can include this module in your pages and components to be able to 
+# create Brut's components without `.new` or without the full classname:
+#
+# @example
+#   class AppPage < Brut::FrontEnd::Page
+#     include Brut::FrontEnd::Components
+#   end
+#
+#   class HomePage < AppPage
+#     def page_template
+#     h1 do
+#       span { "It's }
+#       TimeTag(timestamp: Time.now)
+#     end
+#   end
 module Brut::FrontEnd::Components
   autoload(:FormTag,"brut/front_end/components/form_tag")
   autoload(:Input,"brut/front_end/components/input")
@@ -72,16 +88,24 @@ class Brut::FrontEnd::Component < Phlex::HTML
       }
     end
 
-    # Return a component that you would like Brut to instantiate.
-    # This will use keyword injection to create the component, which means that if the component
-    # doesn't require any data from this component, you do not need to pass through those values.
-    # For example, you may have a component that renders the flash message.  To avoid requiring your component to
-    # be passed the flash, a global component can be injected with it from Brut.
+    # Render (in Phlex parlance) a component that you would like Brut to
+    # instantiate.  This is useful when you want to use a component that
+    # only requires values from the {Brut::FrontEnd::RequestContext}. By
+    # using this method, *this* component does not have to receive
+    # data from the {Brut::FrontEnd::RequestContext} that only serves to pass
+    # to the component you use here.
+    #
+    # For example, you may have a component that renders the flash message.  To avoid requiring *this* component/page to be passed the flash, a global component can be injected with it from Brut.
+    #
+    # This component *will* be rendered into the Phlex context. Do not call
+    # `render` on the result, nor rely on the return value.
     #
-    # @return [Object] instance of `component_klass`, as created by Brut. This will
-    #         not render the component.
+    # @param [Class] component_klass the component class to use in the view.
+    #        This class's
+    #        initializer must only require information available from the 
+    #        {Brut::FrontEnd::RequestContext}.
     def global_component(component_klass)
-      Brut::FrontEnd::RequestContext.inject(component_klass)
+      render Brut::FrontEnd::RequestContext.inject(component_klass)
     end
   end
   include Helpers

data/lib/brut/front_end/components/inputs/select_tag_with_options.rb

@@ -27,14 +27,14 @@ class Brut::FrontEnd::Components::Inputs::SelectTagWithOptions < Brut::FrontEnd:
   #        to be used as the `value` attribute and option text content, respectively.
   #
   # @return [Brut::FrontEnd::Components::Inputs::SelectTagWithOptions] the select input ready to be placed into a view.
-  def self.for_form_input(form:,
-                          input_name:,
-                          options:,
-                          include_blank: false,
-                          value_attribute:,
-                          option_text_attribute:,
-                          index: nil,
-                          html_attributes: {})
+  def initialize(form:,
+                 input_name:,
+                 options:,
+                 include_blank: false,
+                 value_attribute:,
+                 option_text_attribute:,
+                 index: nil,
+                 html_attributes: {})
     html_attributes = html_attributes.map { |key,value| [ key.to_sym, value ] }.to_h
     default_html_attributes = {}
     index ||= 0
@@ -54,84 +54,26 @@ class Brut::FrontEnd::Components::Inputs::SelectTagWithOptions < Brut::FrontEnd:
              input.name
            end
 
-    Brut::FrontEnd::Components::Inputs::SelectTagWithOptions.new(
-      name: name,
-      options:,
-      selected_value: input.value,
-      value_attribute:,
-      option_text_attribute:,
-      include_blank:,
-      html_attributes: default_html_attributes.merge(html_attributes)
-    )
-  end
+    input_value = input.value
 
-  # Create the element.
-  #
-  # @param [String] name the name of the input
-  # @param [Array<Object>] options An array of objects represented what is being selected.
-  #        These can be any object and are ideally whatever domain object or
-  #        data type you want on the backend to represent this selection.
-  # @param [Symbol|String] value_attribute the name of an attribute to determine an option's value.
-  #        This will be called on each element of `options` to get the value used for the `<option>`'s
-  #        `value` attribute.  The value returned by `value_attribute` should be unique amongst the
-  #        `options` provided *and* be distinct from whatever `value` is used for `include_blank`.
-  # @param [String] selected_value the value of the selected option. Note that this is the *value*
-  #        of the selected option, not the selected option itself. To set the selected value
-  #        based on a selected option, omit this and use `selected_option`
-  # @param [String] selected_option the selected option. Note that `value_attribute` will be called
-  #        on this to determine the selected value to use when generating HTML. Also note that
-  #        this object must be in `options` or an exeception is raised.
-  # @param [Symbol|String] option_text_attribute the name of an attribute to determine the text for an option.
-  #        This will be called on each element of `options` to get the value used for the `<option>`'s
-  #        text content.  The value returned by `option_text_attribute` need not be unique, though if it
-  #        is not unique, it will certainly be confusing.
-  # @param [Hash] html_attributes any additional HTML attributes to include on the `<select>` element.
-  # @param [false|true|Hash] include_blank configure how and if to include a blank element in the select.
-  #        If this is false, there will be no blank element. If it's `true`, there will be one with
-  #        no value or text.  If this is a `Hash` it must contain a `value:` key and a `text_content:` key
-  #        to be used as the `value` attribute and option text content, respectively.
-  #
-  # @raise ArgumentError if `selected_option` is present, but not in `options` or if `selected_value` is
-  #        present, but no option's value for `value_attribute` is that value.
-  #
-  # XXX: Why does this not ask the form for the selected_value?
-  # XXX: This doesn't do well when values are strings
-  def initialize(name:,
-                 options:,
-                 value_attribute:,
-                 selected_value: nil,
-                 selected_option: nil,
-                 option_text_attribute:,
-                 include_blank: false,
-                 html_attributes:)
     @options                = options
     @include_blank          = IncludeBlank.from_param(include_blank)
     @value_attribute        = value_attribute
     @option_text_attribute  = option_text_attribute
-    @html_attributes        = html_attributes
+    @html_attributes        = default_html_attributes.merge(html_attributes)
     @html_attributes[:name] = name
 
-    if selected_value.nil?
-      if selected_option.nil?
-        @selected_value = nil # explicitly nothing is selected
-      else
-        option = options.detect { |option|
-          option.send(@value_attribute) == selected_option.send(@value_attribute)
-        }
-        if option.nil?
-          raise ArgumentError, "selected_option #{selected_option} (with #{value_attribute} '#{selected_option.send(value_attribute)}') was not found in options"
-        end
-        @selected_value = option.send(@value_attribute)
-      end
+    if input_value.nil?
+      @selected_value = nil # explicitly nothing is selected
     else
-      if selected_value.kind_of?(Array)
-        raise "WTF: #{name}"
+      if input_value.kind_of?(Array)
+        raise "WTF: #{name}" # XXX?
       end
       option = options.detect { |option|
-        selected_value == option.send(@value_attribute)
+        input_value == option.send(@value_attribute)
       }
       if option.nil?
-        raise ArgumentError, "selected_value #{selected_value} was not the value for #{value_attribute} on any of the options: #{options.map { |option| option.send(value_attribute) }.join(', ')}"
+        raise ArgumentError, "selected_value #{input_value} was not the value for #{value_attribute} on any of the options: #{options.map { |option| option.send(value_attribute) }.join(', ')}"
       end
       @selected_value = option.send(@value_attribute)
     end

data/lib/brut/front_end/forms/constraint_violation.rb

@@ -2,22 +2,6 @@
 # form-related classes.
 class Brut::FrontEnd::Forms::ConstraintViolation
 
-  # These are underscorized versions of the attributes of the browser's `ValidityState`'s properties.
-  #
-  # @see https://developer.mozilla.org/en-US/docs/Web/API/ValidityState
-  CLIENT_SIDE_KEYS = [
-    "bad_input",
-    "custom_error",
-    "pattern_mismatch",
-    "range_overflow",
-    "range_underflow",
-    "step_mismatch",
-    "too_long",
-    "too_short",
-    "type_mismatch",
-    "value_missing",
-  ]
-
   # @return [String] the key fragment representing the violation
   attr_reader :key
   # @return [Hash] interpolated values useful in rendering the actual message
@@ -27,11 +11,11 @@ class Brut::FrontEnd::Forms::ConstraintViolation
   #
   # @param [String|Symbol] key I18n key fragment representing this violation.
   # @param [Hash|nil] context interpolated values useful in rendering the message
-  # @param [true|:based_on_key] server_side If `:based_on_key`, {#client_side?} will return true if `key` is in {.CLIENT_SIDE_KEYS}.
+  # @param [true|:based_on_key] server_side If `:based_on_key`, {#client_side?} will return true if `key` is in {ValidityState.KEYS}.
   # If `true`, {#client_side?} will return false no matter what.
   def initialize(key:,context:, server_side: :based_on_key)
     @key = key.to_s
-    @client_side = CLIENT_SIDE_KEYS.include?(@key) && server_side != true
+    @client_side = Brut::FrontEnd::Forms::ValidityState::KEYS.include?(@key) && server_side != true
     @context = context || {}
     if !@context.kind_of?(Hash)
       raise "#{self.class} created for key #{key} with an invalid context: '#{context}/#{context.class}'. Context must be nil or a hash"

data/lib/brut/front_end/forms/input.rb

@@ -82,14 +82,14 @@ class Brut::FrontEnd::Forms::Input
     step_mismatch = false
 
     @validity_state = Brut::FrontEnd::Forms::ValidityState.new(
-      value_missing: missing,
-      too_short: too_short,
-      too_long: too_short,
-      range_overflow: range_overflow,
-      range_underflow: range_underflow,
-      pattern_mismatch: pattern_mismatch,
-      step_mismatch: step_mismatch,
-      type_mismatch: type_mismatch,
+      valueMissing: missing,
+      tooShort: too_short,
+      tooLong: too_short,
+      rangeOverflow: range_overflow,
+      rangeUnderflow: range_underflow,
+      patternMismatch: pattern_mismatch,
+      stepMismatch: step_mismatch,
+      typeMismatch: type_mismatch,
     )
     @value = new_value
   end

data/lib/brut/front_end/forms/input_declarations.rb

@@ -12,8 +12,8 @@ module Brut::FrontEnd::Forms::InputDeclarations
   end
 
   # Declares a select for this form, to be modeled via an HTML `<SELECT>` tag. Note that this will not define the values that appear
-  # in the select.  That is done when the select is rendered, which you might do with
-  # {Brut::FrontEnd::Components::Inputs::Select.for_form_input}
+  # in the select.  That is done when the select is rendered, which you might do with a
+  # {Brut::FrontEnd::Components::Inputs::Select}
   #
   # @param [String] name The name of the input (used in the `name` attribute)
   # @param [Hash] attributes Attributes to be used on the tag that represent its contraints. See {Brut::FrontEnd::Forms::SelectInputDefinition}
@@ -28,7 +28,7 @@ module Brut::FrontEnd::Forms::InputDeclarations
   # input tags.
   #
   # Note that this is not where you would define the possible values for the group. That is done in
-  # {Brut::FrontEnd::Components::Inputs::RadioButton.for_form_input}.
+  # {Brut::FrontEnd::Components::Inputs::RadioButton}.
   #
   # @param [String] name The name of the group (used in the `name` attribute)
   # @param [Hash] attributes Attributes to be used on the tag that represent its contraints. See {Brut::FrontEnd::Forms::RadioButtonGroupInputDefinition}

data/lib/brut/front_end/forms/radio_button_group_input.rb

@@ -32,7 +32,7 @@ class Brut::FrontEnd::Forms::RadioButtonGroupInput
               end
 
     @validity_state = Brut::FrontEnd::Forms::ValidityState.new(
-      value_missing: missing,
+      valueMissing: missing,
     )
     @value = new_value
   end

data/lib/brut/front_end/forms/select_input.rb

@@ -30,7 +30,7 @@ class Brut::FrontEnd::Forms::SelectInput
               end
 
     @validity_state = Brut::FrontEnd::Forms::ValidityState.new(
-      value_missing: missing,
+      valueMissing: missing,
     )
     @value = new_value
   end

data/lib/brut/front_end/forms/validity_state.rb

@@ -3,6 +3,11 @@
 # In a sense, this is a wrapper for one or more {Brut::FrontEnd::Forms::ConstraintViolation} instances in the
 # context of an input.
 #
+# This class also holds the logic related to client- vs. server-side constraint
+# violations.  As such, {.KEYS} is the list of known client-side 
+# constraint violation keys, as defined by browser's `ValidityState` class. These
+# are left as camel-case to make this clear.
+#
 # @see https://developer.mozilla.org/en-US/docs/Web/API/ValidityState
 class Brut::FrontEnd::Forms::ValidityState
   include Enumerable
@@ -46,5 +51,23 @@ class Brut::FrontEnd::Forms::ValidityState
     end
   end
 
+
+  # These are the attributes of the browser's `ValidityState`'s properties.
+  # They are left as camel-case to clearly indicate they come from the browser.
+  #
+  # @see https://developer.mozilla.org/en-US/docs/Web/API/ValidityState
+  KEYS = [
+    "badInput",
+    "customError",
+    "patternMismatch",
+    "rangeOverflow",
+    "rangeUnderflow",
+    "stepMismatch",
+    "tooLong",
+    "tooShort",
+    "typeMismatch",
+    "valueMissing",
+  ]
+
 end
 

data/lib/brut/spec_support/handler_support.rb

@@ -6,7 +6,7 @@ require_relative "session_support"
 #
 #
 # * `have_redirected_to` to check that the handler redirected to a give URI
-# * `have_rendered` to check that the handler rendered a specific page
+# * `have_generated` to check that the handler rendered a specific page
 # * `have_returned_http_status` to check that the handler returned an HTTP status
 module Brut::SpecSupport::HandlerSupport
   include Brut::SpecSupport::FlashSupport

data/lib/brut/spec_support/matcher.rb

@@ -8,7 +8,7 @@ require_relative "matchers/have_constraint_violation"
 require_relative "matchers/have_html_attribute"
 require_relative "matchers/have_i18n_string"
 require_relative "matchers/have_redirected_to"
-require_relative "matchers/have_rendered"
+require_relative "matchers/have_generated"
 require_relative "matchers/have_returned_http_status"
 require_relative "matchers/have_returned_rack_response"
 require_relative "matchers/have_link_to"

data/lib/brut/spec_support/matchers/be_a_bug.rb

@@ -12,3 +12,14 @@ RSpec::Matchers.define :be_a_bug do
 
   supports_block_expectations
 end
+
+# Block-based matcher that expects the blog to 
+# raise a {Brut::Framework::Errors::Bug}.
+#
+# @example
+#   expect {
+#     SomeClass.new(value: :invalid)
+#   }.to be_a_bug
+#
+class Brut::SpecSupport::Matchers::BeABug
+end

data/lib/brut/spec_support/matchers/be_page_for.rb

@@ -14,3 +14,13 @@ RSpec::Matchers.define :be_page_for do |klass|
     end
   end
 end
+
+# Matcher for end-to-end tests to assert that the current page
+# is the page you expect it to be.  This is based on the
+# {Brut::FrontEnd::Components::PageIdentifier} component, which must
+# be included on the page for this matcher to work.
+#
+# @example
+#   expect(page).to be_page_for(HomePage)
+class Brut::SpecSupport::Matchers::BePageFor
+end

data/lib/brut/spec_support/matchers/be_routing_for.rb

@@ -9,3 +9,21 @@ RSpec::Matchers.define :be_routing_for do |klass,**args|
   end
 
 end
+
+# Matcher used for handlers (or any code that returns a `URI`)
+# to assert that the URI is for a given page with the given set of parameters
+#
+# @example
+#   result = handler.handle
+#   expect(result).to be_routing_for(HomePage)
+#
+# @example with parameters
+#   result = handler.handle
+#   expect(result).to be_routing_for(WidgetsByWidgetIdPage, id: widget.external_id)
+#
+# @example with anchor
+#   result = handler.handle
+#   expect(result).to be_routing_for(MessagesPage, anchor: "latest_message")
+#
+class Brut::SpecSupport::Matchers::BeRoutingFor
+end

data/lib/brut/spec_support/matchers/have_constraint_violation.rb

@@ -29,6 +29,16 @@ RSpec::Matchers.define :have_constraint_violation do |field,key:,index:nil|
   end
 end
 
+# Matcher to check that a from has a specific constraint violation.
+#
+# @example
+#    expect(form).to have_constraint_violation(:email, key: :required)
+#
+# @example Index fields (requires that the third email field have a constraint violation)
+#    expect(form).to have_constraint_violation(:email, key: :required, index: 2)
+#
+# @example Negated
+#    expect(form).not_to have_constraint_violation(:email, key: :required)
 class Brut::SpecSupport::Matchers::HaveConstraintViolation
   attr_reader :fields_found
   attr_reader :keys_on_field_found

data/lib/brut/spec_support/matchers/have_generated.rb

@@ -0,0 +1,28 @@
+# Handler
+RSpec::Matchers.define :have_generated do |component_or_page|
+  match do |result|
+    result.class.ancestors.include?(component_or_page)
+  end
+
+  failure_message do |result|
+    "Expected a #{component_or_page} to be generated, but got #{result}"
+  end
+  failure_message_when_negated do |result|
+    "Got #{component_or_page} when not expected"
+  end
+
+end
+
+# Matcher to check that a handler generated a specific page
+# (as opposed to redirected to a page). This works for components
+# as well, in the case of Ajax requests.
+#
+# @example
+#   result = handler.handle(form:)
+#   expect(result).to have_generated(NewWidgetPage)
+#
+# @example Ajax request
+#   result = handler.handle(form:, xhr: true)
+#   expect(result).to have_generated(WidgetResponseComponent)
+class Brut::SpecSupport::Matchers::HaveGenerated
+end

data/lib/brut/spec_support/matchers/have_html_attribute.rb

@@ -25,6 +25,16 @@ RSpec::Matchers.define :have_html_attribute do |attribute|
   end
 end
 
+# Used in component or page specs to check that a given node
+# has a particular HTML attribnute, or an attribute with a speecific value.
+#
+# @example
+#   result = generate_and_parse(page)
+#   expect(result.e!("blockquote")).to have_html_attribute(:id)
+#
+# @example Expecting a value as well
+#   result = generate_and_parse(page)
+#   expect(result.e!("blockquote")).to have_html_attribute(id: "foo")
 class Brut::SpecSupport::Matchers::HaveHTMLAttribute
 
   attr_reader :error

data/lib/brut/spec_support/matchers/have_i18n_string.rb

@@ -24,3 +24,16 @@ RSpec::Matchers.define :have_i18n_string do |key,**args|
   end
 end
 
+# Used in component or page specs to check if a Nokogiri node's 
+# text contains a specific i18n string, without you having
+# to use `t` to look it up.
+#
+# @example
+#   result = generate_and_parse(page)
+#   expect(result.e!("h3")).to have_i18n_string(:greeting)
+#
+# @example I18n string with parameters
+#   result = generate_and_parse(page)
+#   expect(result.e!("h3")).to have_i18n_string(:user_greeting, email: account.email)
+class Brut::SpecSupport::Matchers::HaveI18nString
+end

data/lib/brut/spec_support/matchers/have_link_to.rb

@@ -13,3 +13,18 @@ RSpec::Matchers.define :have_link_to do |page_klass,**args|
     "Did not expect to find link to #{page_klass.routing(**args)}."
   end
 end
+
+# Used on a component/page spec to check that there is a link
+# to a specific routing.  This handles creating a CSS selector
+# like `[href="#{page_klass.routing(**args)}"]`.
+#
+# @example
+#   result = generate_and_parse(page)
+#   expect(result.e!("nav")).to have_link_to(HomePage)
+#
+# @example link with parameters
+#   result = generate_and_parse(page)
+#   expect(result.e!("nav")).to have_link_to(WidgetsByWidgetIdPage, id: widget.id)
+#
+class Brut::SpecSupport::Matchers::HaveLinkTo
+end

data/lib/brut/spec_support/matchers/have_redirected_to.rb

@@ -37,5 +37,28 @@ RSpec::Matchers.define :have_redirected_to do |page_or_uri,**page_params|
   failure_message_when_negated do |result|
     "Got a redirect when it wasn't expected"
   end
+end
 
+# Used on handler specs to check that a response has
+# redirected to a page or URI.  Can also be used
+# with {Brut::SpecSupport::ComponentSupport#generate_result} to 
+# check that a Page's {Brut::FrontEnd::Page#before_generate} method
+# did what you expect
+#
+# @example
+#   result = handler.handle
+#   expect(result).to have_redirected_to(HomePage)
+#
+# @example with parameters
+#   result = handler.handle
+#   expect(result).to have_redirected_to(WidgetsByWidgetIdPage, id: widget.id)
+#
+# @example arbitrary URI
+#   result = handler.handle
+#   expect(result).to have_redirected_to("http://kagi.com")
+#
+# @example testing a `before_generate` method
+#   result = generate_result(page)
+#   expect(result).to have_redirected_to(LoginPage)
+class Brut::SpecSupport::Matchers::HaveRedirectedTo
 end

data/lib/brut/spec_support/matchers/have_returned_http_status.rb

@@ -31,5 +31,25 @@ RSpec::Matchers.define :have_returned_http_status do |http_status=nil|
       "Got #{http_status} when not expected (#{result.class} was returned)"
     end
   end
+end
 
+# Used on handler specs to check that a response returned
+# a particular HTTP status code. Can also be used
+# with {Brut::SpecSupport::ComponentSupport#generate_result} to 
+# check that a Page's {Brut::FrontEnd::Page#before_generate} method
+# did what you expect
+#
+# @example
+#   result = handler.handle
+#   expect(result).to have_returned_http_status(404)
+#
+# @example dont' care what status, just that one was returned instead of a page generation
+#   result = handler.handle
+#   expect(result).to have_returned_http_status
+#
+#
+# @example testing a `before_generate` method
+#   result = generate_result(page)
+#   expect(result).to have_returned_http_status(403)
+class Brut::SpecSupport::Matchers::HaveReturnedHttpStatus
 end

data/lib/brut/spec_support/matchers/have_returned_rack_response.rb

@@ -42,3 +42,25 @@ RSpec::Matchers.define :have_returned_rack_response do |http_status: :any, heade
   end
 
 end
+
+# Used on handler specs to check that a response returned
+# a Rack response. Can also be used
+# with {Brut::SpecSupport::ComponentSupport#generate_result} to 
+# check that a Page's {Brut::FrontEnd::Page#before_generate} method
+# did what you expect
+#
+# The matcher expects these keyword arguments:
+#
+# * `http_status:` - the expected HTTP status code as a number, or `:any` (the default), if it's not relevant to the test.
+# * `headers:` - the expected headers as a Hash of Strings to Strings, or `:any` (the default), if they are not relevant to the test.
+# * `body:` - the expected body, or `:any` (the default), if it is not relevant to the test.
+#
+# @example
+#   result = handler.handle
+#   expect(result).to have_returned_rack_response(
+#                        http_status: 200,
+#                        headers: { "Content-Type" => "text/html" }
+#                        )
+#
+class Brut::SpecSupport::Matchers::HaveReturnedRackResponse
+end

data/lib/brut/version.rb

@@ -1,4 +1,4 @@
 module Brut
   # @!visibility private
-  VERSION = "0.0.26"
+  VERSION = "0.0.27"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brut
 version: !ruby/object:Gem::Version
-  version: 0.0.26
+  version: 0.0.27
 platform: ruby
 authors:
 - David Bryant Copeland
@@ -614,6 +614,7 @@ files:
 - brutrb.com/javascript.md
 - brutrb.com/jobs.md
 - brutrb.com/keyword-injection.md
+- brutrb.com/lsp.md
 - brutrb.com/markdown-examples.md
 - brutrb.com/middleware.md
 - brutrb.com/not-released.md
@@ -1182,11 +1183,11 @@ files:
 - lib/brut/spec_support/matchers/be_page_for.rb
 - lib/brut/spec_support/matchers/be_routing_for.rb
 - lib/brut/spec_support/matchers/have_constraint_violation.rb
+- lib/brut/spec_support/matchers/have_generated.rb
 - lib/brut/spec_support/matchers/have_html_attribute.rb
 - lib/brut/spec_support/matchers/have_i18n_string.rb
 - lib/brut/spec_support/matchers/have_link_to.rb
 - lib/brut/spec_support/matchers/have_redirected_to.rb
-- lib/brut/spec_support/matchers/have_rendered.rb
 - lib/brut/spec_support/matchers/have_returned_http_status.rb
 - lib/brut/spec_support/matchers/have_returned_rack_response.rb
 - lib/brut/spec_support/rspec_setup.rb

data/lib/brut/spec_support/matchers/have_rendered.rb

@@ -1,14 +0,0 @@
-# Handler
-RSpec::Matchers.define :have_rendered do |component_or_page|
-  match do |result|
-    result.class.ancestors.include?(component_or_page)
-  end
-
-  failure_message do |result|
-    "Expected a #{component_or_page} to be rendered, but got #{result}"
-  end
-  failure_message_when_negated do |result|
-    "Got #{component_or_page} when not expected"
-  end
-
-end