brut 0.17.0 → 0.18.0

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

@@ -1,208 +0,0 @@
-# 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.
-
-## Overview
-
-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:
-
-* 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.
-
-To access the session, declare it as a keyword argument to your page, handler, or
-global component's intitializer:
-
-```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.
-
-Let's say the currently logged-in visitor is available in the session.  Your
-`HomePage` could look like so:
-
-```ruby
-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
-```
-
-Let's suppose a `LoginHandler` exists, that can set a value for `current_visitor`:
-
-```ruby
-class LoginHandler < AppHandler
-  def initialize(form:, session:)
-    @form    = form
-    @session = session
-  end
-
-  def handle
-    visitor = Login.from_form(form:) # assume this exists
-    if visitor
-      @sesion.login!(visitor:)
-    else
-      # ...
-    end
-  end
-end
-```
-
-`AppSession` would need to look like so:
-
-```ruby
-class AppSession < Brut::FrontEnd::Session
-  def login!(visitor:)
-    self[:current_visitor_id] = visitor.id
-  end
-
-  def current_visitor
-    DB::Visitor.find(id: self[:current_visitor_id])
-  end
-end
-```
-
-Brut encourages your session to be a rich object.  You can declare any methods you
-like:
-
-```ruby
-class AppSession < Brut::FrontEnd::Session
-  def logged_in? = !!self.current_visitor
-end
-```
-
-> [!NOTE]
-> When dealing with auth, you can leverage
-> keyword injection beyond injecting the session.  This is
-> discussed in [the auth recipe](/recipes/authentication.md)
-
-### Flash
-
-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
-```
-
-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 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.
-
-The values are expected to be I18n keys:
-
-```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
-end
-```
-
-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
-```
-
-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. 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
-
-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
-
-> [!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 May 7, 2025_
-
-The session is based on [`Rack::Session`](https://github.com/rack/rack-session), which is configured explicitly
-in your app's `config.ru`. (TBD: WHY?)
-
-The session object itself is created on demand for any route hook that needs it.
-Since `Brut::FrontEnd::RouteHooks::SetupRequestContext` requires the session, the
-`Brut::FrontEnd::RequestContext` is created here and given the session (and flash) that is used for subsequent
-hooks and HTML generation.
-
-The flash is created largely on-demand and is a special hash serialized into the session.  The hash contains the
-current age of the flash and then all the messages.  This format could use improvement and may change.
-`Brut::FrontEnd::RouteHooks::AgeFlash` is a route hook that handles increasing the age of the flash, however the
-flash itself controls when to "age out" messages.  None of this is currently configurable.
-

data/brutrb.com/form-constraints.md

@@ -1,266 +0,0 @@
-# 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.ss` prepended to it (for **c*onstratin **v**iolation, **s**server **s**ide).  Thus, the key in the above example is `"cv.ss.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" client-side 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.cs.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" client-side 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-generated server-side>
-    This name has already been taken.
-  </brut-cv>
-</brut-cv-messages>
-```
-
-The `server-genereted` and `server-side` attributes 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" client-side 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-generated] {
-  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.