brut 0.0.29 → 0.2.0

data/brutrb.com/flash-and-session.md

@@ -1,205 +1,189 @@
 # Flash and Session
 
-Brut sessions are stored in cookies, encrypted to prevent tampering.  The *flash*, which is a way to temporarily
-store small bits of information between page loads, is encoded in the session.
+Brut sessions are stored in cookies, encrypted to prevent tampering.  The *flash*, which is a way to temporarily store small bits of information between page loads, is encoded in the session.
 
 ## Overview
 
-Unlike Rails, the session and flash are presented to you as objects, not Hashes.  By declaring the `session:`
-parameter on an initializer, you'll be given the current session for the request as an `AppSession`, which
-inherits from `Brut::FrontEnd::Session`.  Similarly, declaring `flash:`, you'll get a `Brut::FrontEnd::Flash`.
+Unlike Rails, the session and flash are presented to you as objects, not Hashes of Whatever.  By declaring the `session:`
+parameter on an initializer, you'll be given the current session for the request as an `AppSession`, which inherits from `Brut::FrontEnd::Session`.  Similarly, declaring `flash:`, you'll get a `Brut::FrontEnd::Flash`.
 
 The idea is to use Ruby's type system to describe what data is in the session and flash.
 
 ### Session
 
-Brut's session is somewhat richer than you might get from other frameworks.  In particular, the session can
-provide you:
+Brut's session is somewhat richer than you might get from other frameworks.  In particular, the session can provide you:
 
 * The current `Brut::I18n::HTTPAcceptLanguage`, which is the visitor's locale. See [I18n](/i18n) for how this
 works and how to use this value.
 * The timezone as provided by the browser.
 * An explicitly-set timezone that may or may not be what the browser provided.  See [Space-Time Continuum](/space-time-continuum) for more details.
 
-The session also handles serializing the flash to and from the browser's cookies and can store any arbitrary data
-you like via `[]`.  You are encouraged to add methods to your app's `AppSession` to make it explicit what you are
-storing.
+To access the session, declare it as a keyword argument to your page, handler, or
+global component's intitializer:
 
-Let's  see the [route hook](/hooks) from  the [pages](/pages) section again.
+```ruby
+class HomePage < AppPage
+  def initialize(session:)
+    @session = session
+  end
+end
+```
+
+When you create your Brut app, your `AppSession` won't have anything in it, although
+it's a `Brut::FrontEnd::Session`, so you can certainly use `[]` and `[]=` on it.
+However, you are encouraged to declare methods that describe precisely what is in
+the session.
 
-> [!CAUTION]
-> This hook is not production-ready. It lacks certain error-handling situations and
-> makes an assumption about how the session is managed. It's for demonstration only.
-> The [route hooks](/hooks) section has a more
-> appropriate example.
+Let's say the currently logged-in visitor is available in the session.  Your
+`HomePage` could look like so:
 
 ```ruby
-class RequireAuthBeforeHook < Brut::FrontEnd::RouteHook
-  def before(request_context:,session:)
-    if session.current_user_id
-      user = DB::User.find(id: session.current_user_id)
-      if user
-        request_context[:current_user] = user
+class HomePage < AppPage
+  def initialize(session:)
+    @session = session
+  end
+
+  def view_template
+    h1 do
+      if @session.current_visitor
+        "Hello #{@session.current_visitor.name}"
+      else
+        "Hi!"
       end
     end
   end
 end
 ```
 
-When this hook executes, `session` will be an `AppSession`, serialized from the browser's cookies.  Here's what
-that class might look like:
+Let's suppose a `LoginHandler` exists, that can set a value for `current_visitor`:
 
 ```ruby
-# app/src/front_end/support/app_session.rb
-class AppSession < Brut::FrontEnd::Session
-  def login!(current_user:)
-    self[:current_user_id] = current_user.id
-  end
-
-  def logout!
-    self[:current_user_id] = nil
+class LoginHandler < AppHandler
+  def initialize(form:, session:)
+    @form    = form
+    @session = session
   end
 
-  def logged_in?
-    !!self.current_user_id
+  def handle
+    visitor = Login.from_form(form:) # assume this exists
+    if visitor
+      @sesion.login!(visitor:)
+    else
+      # ...
+    end
   end
-
-  def current_user_id = self[:current_user_id]
 end
 ```
 
-The session is a rich object and not just a thin wrapper over a Hash.  You could even have the session perform
-the lookup in the database:
+`AppSession` would need to look like so:
 
-```ruby {11,14-16}
-# app/src/front_end/support/app_session.rb
+```ruby
 class AppSession < Brut::FrontEnd::Session
-  def login!(current_user:)
-    self[:current_user_id] = current_user.id
-  end
-  def logout!
-    self[:current_user_id] = nil
+  def login!(visitor:)
+    self[:current_visitor_id] = visitor.id
   end
 
-  def logged_in?
-    !!self.current_user
-  end
-
-  def current_user
-    DB::User.find(id: self[:current_user_id])
+  def current_visitor
+    DB::Visitor.find(id: self[:current_visitor_id])
   end
 end
 ```
 
-Now, the hook could call `current_user`:
+Brut encourages your session to be a rich object.  You can declare any methods you
+like:
 
-```ruby {3-5}
-class RequireAuthBeforeHook < Brut::FrontEnd::RouteHook
-  def before(request_context:,session:)
-    if session.logged_in?
-      request_context[:current_user] = session.current_user
-    end
-  end
+```ruby
+class AppSession < Brut::FrontEnd::Session
+  def logged_in? = !!self.current_visitor
 end
 ```
 
-Let's see `LoginHandler` from the [handlers](/handlers) section, to see how to save the current user.  Given what
-we've learned, the declaration of the `session:` parameter to the initializer means the relevant instance of
-`AppSession` will be passed in.
+> [!NOTE]
+> When dealing with auth, you can leverage
+> keyword injection beyond injecting the session.  This is
+> discussed in [the auth recipe](/recipes/authentication.md)
 
-```ruby {20}
-# app/src/front_end/handlers/login_handler.rb
-class LoginHandler < AppHandler
-  def initialize(form:, session:)
-    @form    = form
-    @session = session
-  end
+### Flash
 
-  def handle
-    if !@form.constraint_violations?
-      authorized_user = AuthorizedUser.login(
-        email: form.email,
-        password: form.password
-      )
-      if authorized_user.nil?
-        @form.server_side_constraint_violation(
-          input_name: :email,
-          key: :login_not_found
-        )
-      else
-        session.login!(current_user: authorized_user.user)
-      end
-    end
-    if @form.constraint_violations?
-      LoginPage.new(form: @form)
-    else
-      redirect_to(DashboardPage.routing)
-    end
+To access the flash, declare it as a keyword argument to your page, handler, or
+global component's intitializer:
+
+```ruby {2,4}
+class DeleteWidgetByIdHandler < AppHandler
+  def initialize(widget_id:, flash:)
+    @widget_id = widget_id
+    @flash     = flash
   end
 end
 ```
 
-Brut will handle saving the updated values in the response so when, in this case, the `DashboardPage` is
-rendered, it can see which user is logged in.
-
-### Flash
-
-By default, your app will use Brut's flash class, `Brut::FrontEnd::Flash`.  This is because you typically don't
-need to enhance the flash.  Brut's flash has an "alert" and "notice", and you can use them however you see fit. You can also set arbitrary messages in the flash via `[]`.
+By default, the flash will be a `Brut::FrontEnd::Flash`.  While you can set your own
+class, this is less commonly needed, so Brut doesn't provide one by default.  Like
+the session, you can use `[]`, but are discouraged from this to avoid Hashes of
+Whatever littering your code.
 
-The contents of the flash only survive one request, so anything you set will be available in that session's next
-request, but not after that.
+The default flash provides a `notice` attribute and an `alert` attribute. Their
+values only survive one request, so anything you set will be available in that session's next request, but not after that.
 
-Note that the flash's alert and notice are intended to be I18n keys.  You don't have to use them this way, but it
-is encouraged.  If you pass an array into `alert=` or `notice=`, the elements will be joined to form an I18n key.
+The values are expected to be I18n keys:
 
-You can create your own subclass if you need a richer flash class than the one Brut provides.
-
-First, create your class. It can be anywhere, but we recommend `app/src/front_end/support/app_flash.rb`:
-
-```ruby
-# app/src/front_end/support/app_flash.rb
-class AppFlash < Brut::FrontEnd::Flash
-  # For example
-  def debug=(debug)
-    self[:debug] = debug
+```ruby {5,8}
+  def handle
+    widget = DB::Widget.find!(id: @widget_id)
+    if widget.can_delete?
+      widget.delete
+      @flash.notice = :widget_deleted
+      redirect_to(WidgetsPage)
+    else
+      @flash.alert = :widget_cannot_be_deleted
+      WidgetsPage.new
+    end
   end
-  def debug  = self[:debug]
-  def debug? = !!self.debug
 end
 ```
 
-Then, in your `App`, located in `app/src/app.rb`, use `Brut.container.override` to change the class used for the
-flash:
-
-```ruby
-class App < Brut::Framework::App
-  # ...
-  def initialize
-    Brut.container.override(
-      "flash_class",
-      AppFlash
-    )
+This is only enforced by convention, but you should stick to one convention since
+you will likely create a [global component](/components) for the flash:
+
+```ruby {17}
+class FlashComponent < AppComponent
+  def initialize(flash:)
+    if flash.notice?
+      @message_key = flash.notice
+      @role = :info
+    elsif flash.alert?
+      @message_key = flash.alert
+      @role = :alert
+    end
   end
 
-  # ...
+  def any_message? = !@message_key.nil?
+
+  def view_template
+    if any_message?
+      div(role: @role) do
+        t([ :flash, @message_key ])
+      end
+    end
+  end
 end
 ```
 
-Brut's configuration system is discussed in more detail in [Configuration](/configuration).
+See [using your own Flash class](/recipes/custom-flash) to see how to enhance Brut's
+flash with your own logic.
 
 ## Testing
 
 Testing your session or flash classes may not be super valuable, however they are normal Ruby objects so you can
-test them in a conventional way.  Both classes treat their internals as a Hash, so you can implement and assert
-via the `[]` and `[]=` methods.
+test them in a conventional way. Although you are discouraged from using `[]` and
+`[]=` as the public API of your session or flash, they can be useful for assertions
+or test setup.
 
 ## Recommended Practices
 
-While you can use both the flash and the session has a hash of whatever, your are encouraged to avoid this in
-your production code.  Create well-defined attributes or methods to manipulate these objects using the language
-of your domain.
-
+Do not treat the session or flash as a Hash of Whatever.  Isolate all magic keys to
+the class and provide a rich API.  It doesn't take that much effort and will make
+your app way easier to manage.
 
 ## Technical Notes
 

data/brutrb.com/form-constraints.md

@@ -0,0 +1,266 @@
+# Form Constraint Validations
+
+Aside from simply collecting data and submitting it to the server, form data has
+*constraints* that must be validated before data is accepted.  Brut provides support
+for both client-side and server-side constraints.
+
+## Overview
+
+When validating form data against its constraints, Brut provides assistance in two
+ways:
+
+* Specifying constraint violations that only the server can evaluate.
+* Unifying the user experience for both client-side and server-side constraint violations.
+
+### Specifying Constraints
+
+For both client and server-side constraint violations, Brut uses the
+`Brut::FrontEnd::Forms::ConstraintViolation` class to represent a specific error on
+a specific field. This class is a wrapper around an i18n key, context to generate
+that key's messaging, and a flag indicating if the violation is server or client
+side.
+
+To specify a server-side constraint violation on a form, call
+`server_side_constraint_violation`:
+
+```ruby
+form.server_side_constraint_violation(
+  input_name: :name,
+  key: :name_is_taken
+)
+```
+
+The `input_name` is the same value you used when creating your form class, and `key`
+is an [I18n](/i18n) key that will have `cv.be` prepended to it (for **c*onstratin **v**iolation, **b**ack **e**nd).  Thus, the key in the above example is `"cv.be.name_is_taken"`.
+
+Brut forms will automatically add client-side constraints based on the value
+assigned to the input.  For example, since `name` must be 3 or more characters, this
+code would implicitly set `:rangeOverflow` as a client-side constraint violation:
+
+```ruby
+form.input(:name).value = "xx"
+```
+
+### Accessing Constraints when Generating HTML
+
+`Brut::FrontEnd::Form` provides the method `constraint_violations` to access the
+constraints, however we recommend using the
+`Brut::FrontEnd::Components::ConstraintViolations` component instead. This component
+generates particular markup useful for unifying the UX around constraint violations,
+which we'll discuss in a moment.
+
+```ruby {13,16,19}
+class NewWidgetPage < AppPage
+  include Brut::FrontEnd::Components
+
+  def initialize(form: nil)
+    @form = form || NewWidgetForm.new
+  end
+
+  private attr_reader :form
+
+  def page_template
+    FormTag(for: form) do
+      Components::InputTag(form:, input_name: :name)
+      Components::ConstraintViolations(form: input_name: :name)
+
+      Components::InputTag(form:, input_name: :quantity)
+      Components::ConstraintViolations(form: input_name: :quantity)
+
+      Components::TextareaTag(form:, input_name: :description)
+      Components::ConstraintViolations(form: input_name: :description)
+    end
+  end
+end
+```
+
+Among other things, `ConstraintViolations` will translate all server-side constraint
+violations into the currently selected locale, if there are any.
+
+### Styling Server and Client-Side Constraint Violations
+
+Without any server-side constraint violations, this is the HTML that would be
+generated for the "name" input tag:
+
+```html
+<input type="text" name="name" required minlength="3">
+<brut-cv-messages input-name="name"></brut-cv-messages>
+```
+
+`<brut-cv-messages>` is an autonomous custom element that serves two purposes:
+
+* It is part of how client-side constraint violations are shown to the visitor.
+* It can be used to target CSS for styling, without the need for `<div>` and `data-` elements. It's more explicitly for constraint violation messaging.
+
+To make `<brut-cv-messages>` work with client-side constraint violations, the
+`<form>` must be contained by a `<brut-form>`:
+
+```ruby {2,13}
+def page_template
+  brut_form do
+    FormTag(for: form) do
+      Components::InputTag(form:, input_name: :name)
+      Components::ConstraintViolations(form: input_name: :name)
+
+      Components::InputTag(form:, input_name: :quantity)
+      Components::ConstraintViolations(form: input_name: :quantity)
+
+      Components::TextareaTag(form:, input_name: :description)
+      Components::ConstraintViolations(form: input_name: :description)
+    end
+  end
+end
+```
+
+`<brut-form>` listens for events from the `<form>` it contains. For an "invalid"
+events, it will locate the element relevant to the event, locate its
+`<brut-cv-messages>` tag, and insert one `<brut-cv>` tag for each error from the
+inputs `ValidityState`.  That may look like so:
+
+```html {3}
+<input type="text" name="name" required minlength="3">
+<brut-cv-messages input-name="name">
+  <brut-cv input-name="name" key="rangeUnderflow"></brut-cv>
+</brut-cv-messages>
+```
+
+They `key` attribute is for an I18n key that is expected to be on the page inside a
+`<brut-i18n-translation>` element.  These are typically included in the [layout](/layouts), and generate HTML like so:
+
+```html
+<brut-i18n-translation key="cv.fe.rangeUnderflow"
+                       value="%{field} is too short"></brut-i18n-translation>
+```
+
+`<brut-cv>` will, whenever its `key` attribute is set or changed, locate the
+corrsponding `<brut-i18n-translation>` element, and perform substitution, result in
+this HTML:
+
+```html {4}
+<input type="text" name="name" required minlength="3">
+<brut-cv-messages input-name="name">
+  <brut-cv input-name="name" key="rangeUnderflow">
+    This field is too short
+  </brut-cv>
+</brut-cv-messages>
+```
+
+Presumably, your layout rendered `<brut-i18n-translation>` tags with the visitor's
+chosen locale (which would be the default behavior of the layout included with a new app).
+
+Coming back to the use of `ConstraintViolations`, if there were a server-side
+violation, the same general markup is generated:
+
+```html {3,4}
+<input type="text" name="name" required minlength="3">
+<brut-cv-messages input-name="name">
+  <brut-cv server-side>
+    This name has already been taken.
+  </brut-cv>
+</brut-cv-messages>
+```
+
+The `server-side` attribute is set, which can help with CSS targeting.
+
+The *last* piece of this puzzle is a solution for the issue where forms that have
+not yet been submitted are considered to have invalid values by the browser.
+`<brut-form>` will add the `submitted-invalid` attribute to itself whenever form
+submission has been prevented by invalid attributes.
+
+This might lead to HTML like so:
+
+```html {1}
+<brut-form submitted-invalid>
+  <form ...>
+
+    <!-- .. -->
+
+    <input type="text" name="name" required minlength="3">
+    <brut-cv-messages input-name="name">
+      <brut-cv input-name="name" key="rangeUnderflow">
+        This field is too short
+      </brut-cv>
+    </brut-cv-messages>
+
+    <!-- ... -->
+
+  </form>
+</brut-form>
+```
+
+This is everything you need to style all constraint violations the same:
+
+```css
+/* By default, brut-cv is hidden */
+brut-cv {
+  display: none;
+}
+
+/* brut-cv inside a submitted-invalid
+   OR brut-cv from the server ARE shown */
+brut-form[submitted-invalid] brut-cv,
+brut-cv[server-side] {
+  display: block;
+  color: red; /* e.g. */
+}
+```
+
+If JavaScript is not enabled, everything degrades properly, as long as your handler
+re-checks the client-side validations (we'll discuss in the next module):
+
+```ruby
+def handle
+  # This will be true by virtue of the form's
+  # values having been set to values that violate
+  # one or more client-side violations.
+  if @form.constraint_violations?
+    # ...
+  end
+end
+```
+
+## Testing
+
+Testing client-side validations must be done with end-to-end tests.  Writing code
+like so will work just fine:
+
+```ruby
+button = page.locator("brut-form button")
+button.click
+
+brut_cv = page.locator("brut-cv-messages[input-name='name'] brut-cv")
+expect(brut_cv).to have_text("too short")
+```
+
+Playwright will wait for the `brut-cv` containing the text "too short" to appear on
+the page, so you should not have any race conditions.
+
+## Recommended Practices
+
+### Utility CSS is Tricky Here
+
+Utility CSS like BrutCSS or TailwindCSS isn't well-suited to targeting elements
+based on custom elements or attributes.  You will need to write CSS or need to
+create your own utility CSS for these situations.
+
+In our opinion, writing CSS for something like this isn't a big deal as it can
+reduce duplcation via the use of custom properties from your CSS library/design
+system and it tends to be stable once created.
+
+### Learn to Be OK with the Browser's UX
+
+One complain about client-side constraint violations is that the browser often
+provides UX that you cannot control.  This isn't ideal, but it does have the virtue
+of being accessible and obvious.  Visitors also really don't care about how ugly it
+is as much as you might think.  The utility and accessibility offset is as
+worthwhile tradeoff.
+
+## Technical Notes
+
+> [!IMPORTANT]
+> Technical Notes are for deeper understanding and debugging. While we will try to keep them up-to-date with changes to Brut's
+> internals, the source code is always more correct.
+
+_Last Updated July 6, 2025_
+
+Nothing at this time.