phlexible 3.1.1 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 335d7a198a6dd2e58d52abe064552a739cfd77c9910f294022bd4a96adf4ef92
-  data.tar.gz: ee505e0e79afba25172584437407b99bc9ab52609d0d7c02cf2e29edc91ac20f
+  metadata.gz: 4752fe1e276560bb8cca4c2115aabb11c36958588672cc5ec36d20bd3599d82e
+  data.tar.gz: 854eba7f90f061528db3de98a120bc457a679421103ef84eced0373457b1e3f1
 SHA512:
-  metadata.gz: 58bd0f6dba980c3328127363960d501e9abbc2e84543b3264d418eb30a5e0a3fad8e25a7fa5a1f9a2b3aaa2b4f0e2bc4057813cdc963a63c7c276611052e6502
-  data.tar.gz: 7c082ee6bdfc6ae5f46f680d872b16e6d125dadfd94771b7da5d87151655a4405faf4c5616ae4bb5d56277a3df8dcfa45cfd928b7b0d97f678bcf2543d65f84d
+  metadata.gz: 1ce11414a8a6a792e6a50b20ded0135037dc946267ee802f4ae9f9bb031b22a3689b5eadf821029ad4d29f1ce4599e6d9ffa96ac1b3c4d15285df7f1c37415f9
+  data.tar.gz: 3a825528fc039dffedbbe35a588c52bd9e3c5cdbd336e0e23793d316d1949cbad2dd090a69fb36fe911b57f2b69e46983d17c3022c10177aebc8704975c49f3a

data/.claude/agents/rubocop-reviewer.md

@@ -0,0 +1,31 @@
+You are a RuboCop style reviewer for the Phlexible Ruby gem.
+
+## Project Style Rules
+
+This project enforces strict RuboCop rules. Review changed Ruby files and flag violations.
+
+### Disabled Syntax (hard errors)
+- **No `unless`** — use `if !` or negated conditions instead
+- **No `and` / `or` / `not`** — use `&&` / `||` / `!` instead
+- **No numbered parameters** (`_1`, `_2`) — use named block parameters
+
+### Formatting
+- **Max line length**: 100 characters
+- **Private method indentation**: `indented_internal_methods` — private/protected methods are indented one extra level beneath the access modifier
+- **String literals**: prefer double quotes
+
+### Enabled Plugins
+Review against these RuboCop plugins:
+- `rubocop-rails`
+- `rubocop-minitest`
+- `rubocop-performance`
+- `rubocop-packaging`
+- `rubocop-rake`
+
+## Instructions
+
+1. Read the files that were changed (use `jj diff --name-only` or check recent edits).
+2. For each `.rb` file, check for violations of the rules above.
+3. Run `bundle exec rubocop -P --fail-level C --force-exclusion <file>` to confirm.
+4. Report any issues found, grouped by file, with the specific rule violated and a suggested fix.
+5. If no issues are found, confirm the code passes review.

data/.claude/hooks/protect-files.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path')
+
+# Block edits to lock files and generated gemfiles
+if [[ "$FILE_PATH" == *.lock ]] || [[ "$FILE_PATH" == */gemfiles/*.gemfile ]]; then
+  echo "Do not edit lock files or generated Appraisal gemfiles directly." >&2
+  exit 2
+fi
+
+exit 0

data/.claude/hooks/rubocop-check.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path')
+
+# Only lint Ruby files
+if [[ "$FILE_PATH" != *.rb ]]; then
+  exit 0
+fi
+
+RESULT=$(bundle exec rubocop -P --fail-level C --force-exclusion "$FILE_PATH" 2>&1)
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -ne 0 ]; then
+  echo "$RESULT" >&2
+  exit 2
+fi
+
+exit 0

data/.claude/settings.json

@@ -0,0 +1,27 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/rubocop-check.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

data/.claude/skills/test/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: test
+description: Run tests for the Phlexible gem across the Appraisal matrix
+arguments:
+  - name: appraisal
+    description: "Appraisal to test: phlex1-rails7, phlex1-rails8, phlex2-rails7, phlex2-rails8, or 'all' (default: phlex2-rails8)"
+    default: "phlex2-rails8"
+  - name: file
+    description: "Optional test file path, or path:line for a single test"
+disable-model-invocation: true
+---
+
+Run Phlexible tests using the Appraisal gem for multi-version testing.
+
+## Instructions
+
+1. If `appraisal` is "all", run: `bundle exec appraisal rails test {file}`
+2. Otherwise, run: `bundle exec appraisal {appraisal} rails test {file}`
+3. If no `file` is given, omit it to run the full suite for that appraisal.
+4. Report pass/fail/skip counts from the test output.
+5. If tests fail, summarise which tests failed and why.

data/.rubocop.yml

@@ -12,6 +12,7 @@ AllCops:
   SuggestExtensions: false
   Exclude:
     - "gemfiles/**/*"
+    - "vendor/**/*"
 
 Naming/FileName:
   Exclude:

data/CLAUDE.md

@@ -0,0 +1,80 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Phlexible is a Ruby gem providing helpers and extensions for [Phlex](https://phlex.fun) views in Rails applications. It supports Phlex 1.x and 2.x across Rails 7.2+ and Ruby >= 3.3.
+
+## Commands
+
+### Tests
+
+Tests use Minitest (with maxitest, minitest-focus, minitest-spec-rails). The project uses [Appraisal](https://github.com/thoughtbot/appraisal) to test across multiple Phlex/Rails version combinations defined in `Appraisals`.
+
+```bash
+# Run all tests across all appraisals (phlex1/rails7, phlex1/rails8, phlex2/rails7, phlex2/rails8)
+bundle exec appraisal rails test
+
+# Run tests for a specific appraisal
+bundle exec appraisal phlex2/rails8 rails test
+
+# Run a single test file
+bundle exec appraisal phlex2/rails8 rails test test/phlexible/alias_view_test.rb
+
+# Run a single test by line number
+bundle exec appraisal phlex2/rails8 rails test test/phlexible/alias_view_test.rb:10
+
+# Focus a single test (add `focus` before the test method, provided by minitest-focus)
+```
+
+### Lint
+
+```bash
+bundle exec rubocop -P --fail-level C
+```
+
+### Setup
+
+```bash
+bin/setup
+bundle exec appraisal install
+```
+
+## Architecture
+
+All source code lives under `lib/phlexible/`. Autoloading is handled by Zeitwerk (`Zeitwerk::Loader.for_gem` in `lib/phlexible.rb`).
+
+### Module Organization
+
+Modules are split into two categories:
+
+**Standalone modules** (no Rails dependency):
+- `Phlexible::AliasView` — `extend` in a view to create shortcut methods for rendering other components
+- `Phlexible::Callbacks` — `include` for ActiveSupport::Callbacks-based `before_template`/`after_template`/`around_template` hooks. Also provides `before_layout`/`after_layout`/`around_layout` when used with `AutoLayout`.
+- `Phlexible::PageTitle` — `include` for hierarchical page title management across nested views
+- `Phlexible::ProcessAttributes` — `extend` to intercept and modify HTML element attributes before rendering (Phlex 2.x only; Phlex 1.x has this built-in). Prepends wrappers onto all StandardElements, VoidElements, and custom `register_element` methods.
+
+**Rails-specific modules** (`lib/phlexible/rails/`):
+- `ActionController::ImplicitRender` — convention-based automatic Phlex view rendering (resolves `UsersController#index` to `Users::IndexView`)
+- `ControllerVariables` — explicit interface to expose controller instance variables to Phlex views via `controller_variable` class method
+- `AElement` — overrides `a` tag to pass `href` through Rails `url_for`
+- `ButtonTo` — Phlex component replacing Rails `button_to` helper
+- `Responder` — integration with the [Responders](https://github.com/heartcombo/responders) gem
+- `AutoLayout` — automatic layout wrapping based on view namespace conventions (e.g., `Views::Admin::Index` resolves to `Views::Layouts::Admin`). Includes `ViewAssigns` and `Callbacks`. Layout resolution is cached per class in production.
+- `MetaTags` / `MetaTagsComponent` — define meta tags in controllers, render in views
+
+### Key Patterns
+
+- Modules use `extend` (AliasView, ProcessAttributes) or `include` (Callbacks, PageTitle, ControllerVariables) depending on whether they add class-level or instance-level behavior.
+- `ProcessAttributes` uses `class_eval` with string interpolation to dynamically wrap every HTML element method — be careful when modifying this.
+- `ControllerVariables` depends on both `ViewAssigns` and `Callbacks` internally.
+- `AutoLayout` depends on both `ViewAssigns` and `Callbacks`. Layout resolution is cached in production via `resolved_layout` class method; use `reset_resolved_layout!` to clear.
+- Tests use a Rails dummy app at `test/dummy/` for integration testing with real controllers/routes.
+
+## Style
+
+- RuboCop enforced with `rubocop-rails`, `rubocop-minitest`, `rubocop-performance`, `rubocop-packaging`, `rubocop-rake`.
+- `unless`, `and`/`or`/`not`, and numbered parameters are **disabled** via `rubocop-disable_syntax`.
+- `indented_internal_methods` indentation style (private methods indented one extra level).
+- Max line length: 100 characters.

data/README.md

@@ -2,6 +2,26 @@
 
 A bunch of helpers and goodies intended to make life with [Phlex](https://phlex.fun) even easier!
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [AliasView](#aliasview)
+  - [Callbacks](#callbacks)
+  - [PageTitle](#pagetitle)
+  - [ProcessAttributes](#processattributes)
+  - [Rails::ActionController::ImplicitRender](#railsactioncontrollerimplicitrender)
+  - [Rails::ControllerVariables](#railscontrollervariables)
+  - [Rails::AutoLayout](#railsautolayout)
+  - [Rails::AElement](#railsaelement)
+  - [Rails::ButtonTo](#railsbuttonto)
+  - [Rails::MetaTags](#railsmetatags)
+  - [Rails::Responder](#railsresponder)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Code of Conduct](#code-of-conduct)
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -14,49 +34,39 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-### Rails
+### `AliasView`
 
-#### `ActionController::ImplicitRender`
+Create an alias at a given `element`, to the given view class.
 
-Adds support for default and `action_missing` rendering of Phlex views. So instead of this:
+So instead of:
 
 ```ruby
-class UsersController
-  def index
-    render Views::Users::Index.new
+class MyView < Phlex::HTML
+  def view_template
+    div do
+      render My::Awesome::Component.new
+    end
   end
 end
 ```
 
-You can do this:
-
-```ruby
-class UsersController
-  include Phlexible::Rails::ActionController::ImplicitRender
-end
-```
-
-##### View Resolution
-
-By default, views are resolved using the `phlex_view_path` method, which constructs a path based on the controller and action name. For example, `UsersController#index` will look for `Users::IndexView`.
-
-You can customize this behavior by overriding `phlex_view_path` in your controller:
+You can instead do:
 
 ```ruby
-class UsersController
-  include Phlexible::Rails::ActionController::ImplicitRender
+class MyView < Phlex::HTML
+  extend Phlexible::AliasView
 
-  private
+  alias_view :awesome, -> { My::Awesome::Component }
 
-    def phlex_view_path(action_name)
-      "views/#{controller_path}/#{action_name}"
+  def view_template
+    div do
+      awesome
     end
+  end
 end
 ```
 
-This would resolve `UsersController#index` to `Views::Users::Index` instead.
-
-#### `Callbacks`
+### `Callbacks`
 
 While Phlex does have `before_template`, `after_template`, and `around_template` hooks, they must be defined as regular Ruby methods, meaning you have to always remember to call `super` when redefining any hook method.
 
@@ -82,9 +92,115 @@ end
 
 You can still use the regular `before_template`, `after_template`, and `around_template` hooks as well, but I recommend that if you include this module, that you use callbacks instead.
 
-#### `ControllerVariables`
+When used with `Rails::AutoLayout`, layout callbacks (`before_layout`, `after_layout`, `around_layout`) are also available. See the `Rails::AutoLayout` section below.
+
+### `PageTitle`
+
+Helper to assist in defining page titles within Phlex views. Also includes support for nested views, where each desendent view class will have its title prepended to the page title. Simply include *Phlexible::PageTitle* module and assign the title to the `page_title` class variable:
+
+```ruby
+class MyView
+  include Phlexible::PageTitle
+  self.page_title = 'My Title'
+end
+```
+
+Then call the `page_title` method in the `<head>` of your page.
+
+### `ProcessAttributes`
+
+> This functionality is already built in to **Phlex >= 1**. This module is only needed for **Phlex >= 2**.
+
+Allows you to intercept and modify HTML element attributes before they are rendered. This is useful for adding default attributes, transforming values, or conditionally modifying attributes based on other attributes.
+
+Extend your view class with `Phlexible::ProcessAttributes` and define a `process_attributes` instance method that receives the attributes hash and returns the modified hash.
+
+```ruby
+class MyView < Phlex::HTML
+  extend Phlexible::ProcessAttributes
+
+  def process_attributes(attrs)
+    # Add a default class to all elements
+    attrs[:class] ||= 'my-default-class'
+    attrs
+  end
+
+  def view_template
+    div(id: 'container') { 'Hello' }
+  end
+end
+```
+
+This will output:
+
+```html
+<div id="container" class="my-default-class">Hello</div>
+```
+
+The `process_attributes` method is called for all standard HTML elements and void elements, as well as any custom elements registered with `register_element`.
+
+```ruby
+class MyView < Phlex::HTML
+  extend Phlexible::ProcessAttributes
+
+  register_element :my_custom_element
+
+  def process_attributes(attrs)
+    attrs[:data_processed] = true
+    attrs
+  end
+
+  def view_template
+    my_custom_element(name: 'test') { 'Custom content' }
+  end
+end
+```
+
+### `Rails::ActionController::ImplicitRender`
+
+Adds support for default and `action_missing` rendering of Phlex views. So instead of this:
+
+```ruby
+class UsersController
+  def index
+    render Views::Users::Index.new
+  end
+
+  def show
+    render Views::Users::Show.new
+  end
+end
+```
+
+You can do this:
+
+```ruby
+class UsersController
+  include Phlexible::Rails::ActionController::ImplicitRender
+end
+```
+
+#### View Resolution
+
+By default, views are resolved using the `phlex_view_path` method, which constructs a path based on the controller and action name. For example, `UsersController#index` will look for `Views::Users::IndexView`.
+
+You can customize this behavior by overriding `phlex_view_path` in your controller:
+
+```ruby
+class UsersController
+  include Phlexible::Rails::ActionController::ImplicitRender
+
+  private
+
+    def phlex_view_path(action_name)
+      "views/#{controller_path}/#{action_name}"
+    end
+end
+```
+
+This would resolve `UsersController#index` to `Views::Users::Index` instead.
 
-> Available in **>= 1.0.0**
+### `Rails::ControllerVariables`
 
 > **NOTE:** Prior to **1.0.0**, this module was called `ControllerAttributes` with a very different API. This is no longer available since **1.0.0**.
 
@@ -102,7 +218,7 @@ class Views::Users::Index < Views::Base
 end
 ```
 
-##### Options
+#### Options
 
 `controller_variable` accepts one or many symbols, or a hash of symbols to options.
 
@@ -127,38 +243,103 @@ end
 
 Please note that defining a variable with the same name as an existing variable in the view will be overwritten.
 
-#### `Responder`
+### `Rails::AutoLayout`
 
-If you use [Responders](https://github.com/heartcombo/responders), Phlexible provides a responder to support implicit rendering similar to `ActionController::ImplicitRender` above. It will render the Phlex view using `respond_with` if one exists, and fall back to default rendering.
-
-Just include it in your ApplicationResponder:
+Automatically wraps Phlex views in a layout component based on namespace conventions. Include this module in your view classes to enable automatic layout resolution.
 
 ```ruby
-class ApplicationResponder < ActionController::Responder
-  include Phlexible::Rails::ActionController::ImplicitRender
-  include Phlexible::Rails::Responder
+class Views::Admin::Index < Phlex::HTML
+  include Phlexible::Rails::AutoLayout
+
+  def view_template
+    span { 'admin index' }
+  end
 end
 ```
 
-Then simply `respond_with` in your action method as normal:
+#### Layout Resolution
+
+Layouts are resolved by mapping the view's namespace to a layout class under `Views::Layouts::`. For example:
+
+| View class | Layout resolved |
+|---|---|
+| `Views::Admin::Index` | `Views::Layouts::Admin` |
+| `Views::Admin::Users::Show` | `Views::Layouts::Admin::Users` (falls back to `Views::Layouts::Admin` if not found) |
+| `Views::Dashboard::Index` | `Views::Layouts::Application` (default fallback) |
+
+Layout classes receive the view instance as a constructor argument and yield the view content:
 
 ```ruby
-class UsersController < ApplicationController
-  def new
-    respond_with User.new
+class Views::Layouts::Admin < Phlex::HTML
+  def initialize(view)
+    @view = view
   end
 
+  def view_template(&block)
+    div(id: 'admin-layout', &block)
+  end
+end
+```
+
+#### Controller-Assigned Layouts
+
+You can override automatic resolution by setting a `@layout` instance variable in your controller. The view must also include `ViewAssigns` (which `AutoLayout` includes automatically):
+
+```ruby
+class AdminController < ApplicationController
   def index
-    respond_with User.all
+    @layout = Views::Layouts::Custom
   end
 end
 ```
 
-This responder requires the use of `ActionController::ImplicitRender`, so don't forget to include that in your `ApplicationController`.
+#### Configuration
+
+Three class attributes control layout resolution:
 
-If you use `ControllerVariables` in your view, and define a `resource` attribute, the responder will pass that to your view.
+| Attribute | Default | Description |
+|---|---|---|
+| `auto_layout_view_prefix` | `'Views::'` | Only views matching this prefix get auto-layout. Set to `nil` to match all view classes. |
+| `auto_layout_namespace` | `'Views::Layouts::'` | Namespace where layout classes are looked up. |
+| `auto_layout_default` | `'Views::Layouts::Application'` | Fallback layout when no namespace match is found. Set to `nil` to render without a layout. |
 
-#### `AElement`
+```ruby
+class Views::Base < Phlex::HTML
+  include Phlexible::Rails::AutoLayout
+
+  self.auto_layout_view_prefix = 'Views::'
+  self.auto_layout_namespace = 'Views::Layouts::'
+  self.auto_layout_default = 'Views::Layouts::Application'
+end
+```
+
+#### Layout Callbacks
+
+When `Rails::AutoLayout` is included, `before_layout`, `after_layout`, and `around_layout` callbacks become available (provided by the `Callbacks` module):
+
+```ruby
+class Views::Admin::Index < Phlex::HTML
+  include Phlexible::Rails::AutoLayout
+
+  before_layout :log_render
+
+  def view_template
+    span { 'admin index' }
+  end
+
+  private
+
+    def log_render
+      Rails.logger.info "Rendering with layout"
+    end
+end
+```
+
+#### Caching
+
+Layout resolution is cached per class in production. In development (when `Rails.configuration.enable_reloading` is enabled), layouts are resolved fresh on each render. You can manually clear the cache with `reset_resolved_layout!`.
+
+### `Rails::AElement`
 
 No need to call Rails `link_to` helper, when you can simply render an anchor tag directly with Phlex. But unfortunately that means you lose some of the magic that `link_to` provides. Especially the automatic resolution of URL's and Rails routes.
 
@@ -180,7 +361,13 @@ class MyView < Phlex::HTML
 end
 ```
 
-#### 'ButtonTo`
+You can also pass `:back` as the `href` value, which will use the referrer URL if available, or fall back to `javascript:history.back()`:
+
+```ruby
+a(href: :back) { 'Go back' }
+```
+
+### `Rails::ButtonTo`
 
 Generates a form containing a single button that submits to the URL created by the set of options.
 
@@ -198,7 +385,7 @@ The form submits a POST request by default. You can specify a different HTTP ver
 Phlexible::Rails::ButtonTo.new(:root, method: :patch) { 'My Button' }
 ```
 
-##### Options
+#### Options
 
 - `:class` - Specify the HTML class name of the button (not the form).
 - `:form_attributes` - Hash of HTML attributes for the form tag.
@@ -207,9 +394,7 @@ Phlexible::Rails::ButtonTo.new(:root, method: :patch) { 'My Button' }
 - `:method` - Symbol of the HTTP verb. Supported verbs are :post (default), :get, :delete, :patch,
   and :put.
 
-#### `MetaTags`
-
-> Available in **>= 1.0.0**
+### `Rails::MetaTags`
 
 A super simple way to define and render meta tags in your Phlex views. Just render the
 `Phlexible::Rails::MetaTagsComponent` component in the head element of your page, and define the
@@ -237,98 +422,36 @@ class MyView < Phlex::HTML
 end
 ```
 
-### `AliasView`
-
-Create an alias at a given `element`, to the given view class.
+### `Rails::Responder`
 
-So instead of:
+If you use [Responders](https://github.com/heartcombo/responders), Phlexible provides a responder to support implicit rendering similar to `Rails::ActionController::ImplicitRender` above. It will render the Phlex view using `respond_with` if one exists, and fall back to default rendering.
 
-```ruby
-class MyView < Phlex::HTML
-  def view_template
-    div do
-      render My::Awesome::Component.new
-    end
-  end
-end
-```
-
-You can instead do:
-
-```ruby
-class MyView < Phlex::HTML
-  extend Phlexible::AliasView
-
-  alias_view :awesome, -> { My::Awesome::Component }
-
-  def view_template
-    div do
-      awesome
-    end
-  end
-end
-```
-
-### PageTitle
-
-Helper to assist in defining page titles within Phlex views. Also includes support for nested views, where each desendent view class will have its title prepended to the page title. Simply include *Phlexible::PageTitle* module and assign the title to the `page_title` class variable:
+Just include it in your ApplicationResponder:
 
 ```ruby
-class MyView
-  self.page_title = 'My Title'
+class ApplicationResponder < ActionController::Responder
+  include Phlexible::Rails::ActionController::ImplicitRender
+  include Phlexible::Rails::Responder
 end
 ```
 
-Then call the `page_title` method in the `<head>` of your page.
-
-### `ProcessAttributes`
-
-> This functionality is already built in to **Phlex >= 1**. This module is only needed for **Phlex >= 2**.
-
-Allows you to intercept and modify HTML element attributes before they are rendered. This is useful for adding default attributes, transforming values, or conditionally modifying attributes based on other attributes.
-
-Extend your view class with `Phlexible::ProcessAttributes` and define a `process_attributes` instance method that receives the attributes hash and returns the modified hash.
+Then simply `respond_with` in your action method as normal:
 
 ```ruby
-class MyView < Phlex::HTML
-  extend Phlexible::ProcessAttributes
-
-  def process_attributes(attrs)
-    # Add a default class to all elements
-    attrs[:class] ||= 'my-default-class'
-    attrs
+class UsersController < ApplicationController
+  def new
+    respond_with User.new
   end
 
-  def view_template
-    div(id: 'container') { 'Hello' }
+  def index
+    respond_with User.all
   end
 end
 ```
 
-This will output:
-
-```html
-<div id="container" class="my-default-class">Hello</div>
-```
-
-The `process_attributes` method is called for all standard HTML elements and void elements, as well as any custom elements registered with `register_element`.
-
-```ruby
-class MyView < Phlex::HTML
-  extend Phlexible::ProcessAttributes
-
-  register_element :my_custom_element
-
-  def process_attributes(attrs)
-    attrs[:data_processed] = true
-    attrs
-  end
+This responder requires the use of `ActionController::ImplicitRender`, so don't forget to include that in your `ApplicationController`.
 
-  def view_template
-    my_custom_element(name: 'test') { 'Custom content' }
-  end
-end
-```
+If you use `Rails::ControllerVariables` in your view, and define a `resource` attribute, the responder will pass that to your view.
 
 ## Development
 

data/gemfiles/phlex1_rails7.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    phlexible (3.0.0)
+    phlexible (3.3.0)
       phlex (>= 1.10.0, < 3.0.0)
       phlex-rails (>= 1.2.0, < 3.0.0)
       rails (>= 7.2.0, < 9.0.0)
@@ -416,7 +416,7 @@ CHECKSUMS
   parser (3.3.10.1) sha256=06f6a725d2cd91e5e7f2b7c32ba143631e1f7c8ae2fb918fc4cebec187e6a688
   phlex (1.11.0) sha256=979548e79a205c981612f1ab613addc8fa128c8092694d02f41aad4cea905e73
   phlex-rails (1.2.2) sha256=a20218449e71bc9fa5a71b672fbede8a654c6b32a58f1c4ea83ddc1682307a4c
-  phlexible (3.0.0)
+  phlexible (3.3.0)
   pp (0.6.3) sha256=2951d514450b93ccfeb1df7d021cae0da16e0a7f95ee1e2273719669d0ab9df6
   pretty_please (0.2.0) sha256=1f00296f946ae8ffd53db25803ed3998d615b9cc07526517dc75fcca6af3a0d3
   prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193

data/gemfiles/phlex1_rails8.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    phlexible (3.0.0)
+    phlexible (3.3.0)
       phlex (>= 1.10.0, < 3.0.0)
       phlex-rails (>= 1.2.0, < 3.0.0)
       rails (>= 7.2.0, < 9.0.0)
@@ -414,7 +414,7 @@ CHECKSUMS
   parser (3.3.10.1) sha256=06f6a725d2cd91e5e7f2b7c32ba143631e1f7c8ae2fb918fc4cebec187e6a688
   phlex (1.11.0) sha256=979548e79a205c981612f1ab613addc8fa128c8092694d02f41aad4cea905e73
   phlex-rails (1.2.2) sha256=a20218449e71bc9fa5a71b672fbede8a654c6b32a58f1c4ea83ddc1682307a4c
-  phlexible (3.0.0)
+  phlexible (3.3.0)
   pp (0.6.3) sha256=2951d514450b93ccfeb1df7d021cae0da16e0a7f95ee1e2273719669d0ab9df6
   pretty_please (0.2.0) sha256=1f00296f946ae8ffd53db25803ed3998d615b9cc07526517dc75fcca6af3a0d3
   prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193

data/gemfiles/phlex2_rails7.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    phlexible (3.0.0)
+    phlexible (3.3.0)
       phlex (>= 1.10.0, < 3.0.0)
       phlex-rails (>= 1.2.0, < 3.0.0)
       rails (>= 7.2.0, < 9.0.0)
@@ -422,7 +422,7 @@ CHECKSUMS
   parser (3.3.10.1) sha256=06f6a725d2cd91e5e7f2b7c32ba143631e1f7c8ae2fb918fc4cebec187e6a688
   phlex (2.4.0) sha256=8aad2f0cd792d7b1bd287f15a1f89474c9cacac28120dc33d2a81467ae934067
   phlex-rails (2.4.0) sha256=2bcddbd488681acb25753bab1887d3ac150e644244ff8ba307f2171a4d0195f5
-  phlexible (3.0.0)
+  phlexible (3.3.0)
   pp (0.6.3) sha256=2951d514450b93ccfeb1df7d021cae0da16e0a7f95ee1e2273719669d0ab9df6
   pretty_please (0.2.0) sha256=1f00296f946ae8ffd53db25803ed3998d615b9cc07526517dc75fcca6af3a0d3
   prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193

data/gemfiles/phlex2_rails8.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    phlexible (3.0.0)
+    phlexible (3.3.0)
       phlex (>= 1.10.0, < 3.0.0)
       phlex-rails (>= 1.2.0, < 3.0.0)
       rails (>= 7.2.0, < 9.0.0)
@@ -420,7 +420,7 @@ CHECKSUMS
   parser (3.3.10.1) sha256=06f6a725d2cd91e5e7f2b7c32ba143631e1f7c8ae2fb918fc4cebec187e6a688
   phlex (2.4.0) sha256=8aad2f0cd792d7b1bd287f15a1f89474c9cacac28120dc33d2a81467ae934067
   phlex-rails (2.4.0) sha256=2bcddbd488681acb25753bab1887d3ac150e644244ff8ba307f2171a4d0195f5
-  phlexible (3.0.0)
+  phlexible (3.3.0)
   pp (0.6.3) sha256=2951d514450b93ccfeb1df7d021cae0da16e0a7f95ee1e2273719669d0ab9df6
   pretty_please (0.2.0) sha256=1f00296f946ae8ffd53db25803ed3998d615b9cc07526517dc75fcca6af3a0d3
   prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193

data/lib/phlexible/callbacks.rb

@@ -33,6 +33,18 @@ module Phlexible
       def after_template(*names, &block)
         set_callback(:template, :after, *names, &block)
       end
+
+      def before_layout(*names, &block)
+        set_callback(:layout, :before, *names, &block)
+      end
+
+      def after_layout(*names, &block)
+        set_callback(:layout, :after, *names, &block)
+      end
+
+      def around_layout(*names, &block)
+        set_callback(:layout, :around, *names, &block)
+      end
     end
 
     def around_template

data/lib/phlexible/rails/a_element.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
+require 'phlex/version'
+
 module Phlexible
   module Rails
-    # Calls `url_for` for the `href` attribute.
+    # Calls `url_for` for the `href` attribute, and supports a `:back` `href` value.
     module AElement
       extend ActiveSupport::Concern
 
@@ -10,9 +12,43 @@ module Phlexible
         include Phlex::Rails::Helpers::URLFor
       end
 
-      def a(href:, **, &)
-        super(href: url_for(href), **, &)
+      def a(href:, **attrs, &)
+        attrs[:href] = href == :back ? _back_url : url_for(href)
+
+        super(**attrs, &)
       end
+
+      private
+
+        JAVASCRIPT_BACK = 'javascript:history.back()'
+        private_constant :JAVASCRIPT_BACK
+
+        if Phlex::VERSION >= '2.0.0'
+          def _back_url
+            _filtered_referrer || safe(JAVASCRIPT_BACK)
+          end
+        else
+          # Wraps a value to bypass Phlex 1.x's javascript: href stripping.
+          SafeHref = Struct.new(:value) do
+            def to_phlex_attribute_value = value
+            def to_s = ''
+          end
+          private_constant :SafeHref
+
+          def _back_url
+            _filtered_referrer || SafeHref.new(JAVASCRIPT_BACK)
+          end
+        end
+
+        def _filtered_referrer # :nodoc:
+          controller = respond_to?(:view_context) ? view_context : helpers
+
+          if controller.respond_to?(:request)
+            referrer = controller.request.env['HTTP_REFERER']
+            referrer if referrer && URI(referrer).scheme != 'javascript'
+          end
+        rescue URI::InvalidURIError # rubocop:disable Lint/SuppressedException
+        end
     end
   end
 end

data/lib/phlexible/rails/auto_layout.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Phlexible
+  module Rails
+    module AutoLayout
+      extend ActiveSupport::Concern
+      include Phlexible::Rails::ViewAssigns
+      include Phlexible::Callbacks
+
+      included do
+        define_callbacks :layout
+
+        class_attribute :auto_layout_view_prefix, instance_writer: false, default: 'Views::'
+        class_attribute :auto_layout_namespace, instance_writer: false, default: 'Views::Layouts::'
+        class_attribute :auto_layout_default, instance_writer: false, default: 'Views::Layouts::Application'
+      end
+
+      def around_template
+        layout_class = controller_assigned_layout || self.class.resolved_layout
+        if layout_class
+          run_callbacks :layout do
+            render(@layout = layout_class.new(self)) { super }
+          end
+        else
+          super
+        end
+      end
+
+      class_methods do
+        def resolved_layout
+          if ::Rails.configuration.enable_reloading
+            resolve_layout
+          else
+            return @resolved_layout if defined?(@resolved_layout)
+
+            @resolved_layout = resolve_layout
+          end
+        end
+
+        def reset_resolved_layout!
+          remove_instance_variable(:@resolved_layout) if defined?(@resolved_layout)
+        end
+
+        private
+
+          def resolve_layout
+            view_name = resolve_view_name
+            return nil if view_name.blank?
+
+            prefix = auto_layout_view_prefix
+            return nil if prefix && !view_name.start_with?(prefix)
+
+            resolve_layout_from_namespace(view_name, prefix) ||
+              auto_layout_default&.safe_constantize
+          end
+
+          def resolve_layout_from_namespace(view_name, prefix)
+            strip_prefix = prefix || infer_prefix_from_namespace || ''
+            segments = view_name.delete_prefix(strip_prefix).split('::')[..-2]
+
+            segments.length.downto(1) do |i|
+              klass = "#{auto_layout_namespace}#{segments.first(i).join('::')}".safe_constantize
+              return klass if klass.is_a?(Class)
+            end
+
+            nil
+          end
+
+          def infer_prefix_from_namespace
+            root = auto_layout_namespace&.split('::')&.first
+            "#{root}::" if root
+          end
+
+          def resolve_view_name
+            ancestors.each do |ancestor|
+              return ancestor.name if ancestor.is_a?(Class) && ancestor.name.present?
+            end
+            nil
+          end
+      end
+
+      private
+
+        def controller_assigned_layout
+          return nil if !respond_to?(:view_assigns, true)
+
+          view_assigns['layout']
+        end
+    end
+  end
+end

data/lib/phlexible/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phlexible
-  VERSION = '3.1.1'
+  VERSION = '3.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlexible
 version: !ruby/object:Gem::Version
-  version: 3.1.1
+  version: 3.3.0
 platform: ruby
 authors:
 - Joel Moss
@@ -91,9 +91,15 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/agents/rubocop-reviewer.md"
+- ".claude/hooks/protect-files.sh"
+- ".claude/hooks/rubocop-check.sh"
+- ".claude/settings.json"
+- ".claude/skills/test/SKILL.md"
 - ".rubocop.yml"
 - ".ruby-version"
 - Appraisals
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
@@ -115,6 +121,7 @@ files:
 - lib/phlexible/rails/a_element.rb
 - lib/phlexible/rails/action_controller/implicit_render.rb
 - lib/phlexible/rails/action_controller/meta_tags.rb
+- lib/phlexible/rails/auto_layout.rb
 - lib/phlexible/rails/button_to.rb
 - lib/phlexible/rails/button_to_concerns.rb
 - lib/phlexible/rails/controller_variables.rb
@@ -144,7 +151,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.4
+rubygems_version: 4.0.6
 specification_version: 4
 summary: A bunch of helpers and goodies intended to make life with Phlex even easier!
 test_files: []