Brut Web Framework

BrutCSS is a utility-based CSS library intended for rapid prototyping and designing directly within your HTML. It is not a replacement for CSS, but rather a tool to bootstrap designs using two main components:

1. A Design System: Built on CSS custom properties (variables).
2. Utility Classes: A set of single-purpose CSS classes for direct application in HTML.

Developers can use the low-level utility classes for speed and then abstract them into components (e.g., using Phlex) or custom CSS classes as their project grows.

Brut provides built-in support for OpenTelemetry, an open standard for observability that allows you to monitor and understand your application's behavior in production.

For development environments, Brut includes a pre-configured setup for otel-desktop-viewer, enabling you to visualize instrumentation data locally.

Brut allows you to access any HTTP header by declaring a keyword argument starting with http_.

Naming Convention: Brut converts the standard Rack/CGI header format (e.g., HTTP_USER_AGENT) to lowercase Ruby-friendly names. To access the User-Agent header, use http_user_agent.

Behavior based on argument requirement:

• Required arguments (no default value): If the header is missing, nil is injected. If present, the value is injected (even if it is an empty string).
• Optional arguments (has a default value): If the header is missing, the default value is used. If present, the value is injected.

Components are Phlex components (classes implementing view_template) used to manage HTML complexity. You can instantiate and render them within any view using the render method.

class FlashComponent < AppComponent
  def initialize(flash:)
    # ... logic to set @role and @message_key
  end

  def view_template
    div(role: @role) do
      t([ :flash, @message_key ])
    end
  end
end

# Usage in a page
def page_template
  render FlashComponent.new(flash:)
end

The app/ directory is the heart of your application. It contains the following key components:

• bootstrap.rb: A Ruby file that sets up your app and ensures all necessary files are required correctly.
• config/: Application configuration (e.g., localizations and translations). Note: Brut avoids using YAML for configuration.
• public/: The root directory for public assets served by the application.
• src/: The location for all application source code.

To avoid ambiguity when reading and storing dates across different system or database timezones, Brut recommends using the timestamp with time zone SQL data type.

If your system is set to UTC and you store a timestamp using this type, the value will be read back correctly even if the system timezone is later changed (e.g., to America/Los_Angeles). Using timestamp without time zone (or the standard SQL timestamp) can lead to ambiguity during timezone shifts.

Brut uses custom elements for constraint violations. The <brut-form> element sets a submitted-invalid attribute when a user attempts to submit an invalid form.

To show error messages only after a submission attempt or when they are provided by the server, use the following CSS selectors:

• brut-cv: The custom element for individual error messages.
• brut-form[submitted-invalid] brut-cv: Targets error messages when a form has been submitted and is invalid.
• brut-cv[server-side]: Targets error messages generated by the server.

/* Hide messages by default */
brut-cv {
  display: none;
  color: #A60053;
  font-weight: bold;
  font-size: 1rem;
}

/* Show messages on invalid submission or server-side errors */
brut-form[submitted-invalid] brut-cv,
brut-cv[server-side] {
  display: block;
}

Brut explicitly avoids the Model-View-Controller (MVC) pattern and does not use 'resources' as a core abstraction.

Unlike MVC frameworks that attempt to map HTTP verbs to specific 'resources' (e.g., mapping DELETE to a specific resource action), Brut focuses on the practical reality of web development: serving pages and handling requests. This avoids the complexity and ambiguity often found when trying to force-map business logic and database tables into a strict resource-based RESTful structure.