Phlex Rails

https://github.com/yippee-fun/phlex-rails
Admin
Phlex Rails is a Rails adapter that enables developers to compose object-oriented web views in pure...
Tokens:65,420
Snippets:410
Trust Score:7.1
License:MIT
Update:2 days ago
Show doc for...
Tokens:
Raw
### Installation

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/index.md

Instructions for adding phlex-rails to a Gemfile and requiring it in application code.

```APIDOC
## Installation

### Gemfile
```ruby
gem "phlex-rails"
```

### Require
```ruby
require "phlex-rails"
```
```

--------------------------------

### Rails generate commands for phlex

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/generators.md

Commands to run the install generator and create a component or view. The install generator writes the initializer and base files; the component and view generators create new components and views.

```bash
rails generate phlex:install
rails generate phlex:component Nav
rails generate phlex:view Posts::Index
```

--------------------------------

### Generated view example for Posts::Index

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/generators.md

Example output of the ViewGenerator when running 'rails generate phlex:view Posts::Index'. It produces a namespaced view class at app/views/posts/index.rb.

```ruby
class Views::Posts::Index < Views::Base
  def view_template
    h1 { "Index" }
    p { "Find me in app/views/posts/index.rb" }
  end
end
```

--------------------------------

### Caching example component (Components::Cache)

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/configuration.md

Example Phlex component that uses the cache method to cache its rendered output. With perform_caching = true, the second render with different text returns the cached HTML, as verified by test/cache.test.rb.

```ruby
class Components::Cache < Phlex::HTML
	def initialize(text)
		@text = text
	end

	def cache_store = Rails.cache

	def view_template
		cache do
			h1 { @text }
		end
	end
end
```

--------------------------------

### partial usage example

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/sgml.md

Shows how to use the partial method inside a view template, passing a title and a block that renders content inside the partial.

```ruby
def view_template
	div(class: "around") do
		render partial("card", title: "Hello") do
			h3 { "Hello from inside" }
		end
	end
end
```

--------------------------------

### Generated component example for Card

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/generators.md

Example output of the ComponentGenerator when running 'rails generate phlex:component Card'. It produces a component class at app/components/card.rb.

```ruby
class Components::Card < Components::Base
  def view_template
    h1 { "Card" }
    p { "Find me in app/components/card.rb" }
  end
end
```

--------------------------------

### Install phlex-rails with Gemfile and require

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/index.md

Add the gem to your Gemfile and require it in application code. The require loads lib/phlex-rails.rb which requires lib/phlex/rails.

```ruby
# Gemfile
gem "phlex-rails"

# application code (or via Bundler.require)
require "phlex-rails"   # lib/phlex-rails.rb → require_relative "phlex/rails"
```

--------------------------------

### Use Routes helper in a component

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/helpers.md

Example component that includes the Routes helper and uses posts_path and posts_url in a view template. The comments show the expected output: /posts and http://test.host/posts.

```ruby
class Components::Nav < Phlex::HTML
	include Phlex::Rails::Helpers::Routes

	def view_template
		a(href: posts_path) { "Posts" }   # => /posts
		a(href: posts_url) { "Posts" }    # => http://test.host/posts
	end
end
```

--------------------------------

### config/initializers/phlex.rb template

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/configuration.md

Generated by `rails generate phlex:install`. Registers `app/views` and `app/components` with Rails autoloaders under `Views` and `Components` namespaces, and extends `Components` with `Phlex::Kit`. Classes under these directories must be namespaced accordingly.

```ruby
module Views
end

module Components
  extend Phlex::Kit
end

Rails.autoloaders.main.push_dir(
  Rails.root.join("app/views"), namespace: Views
)

Rails.autoloaders.main.push_dir(
  Rails.root.join("app/components"), namespace: Components
)
```

--------------------------------

### Usage and error handling example

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/never.md

Demonstrates correct and incorrect usage of options_for_select with select_tag. Using the return value as an argument raises Phlex::ArgumentError at render time; calling it inside a block outputs directly to the buffer and works correctly.

```ruby
include Phlex::Rails::Helpers::SelectTag
include Phlex::Rails::Helpers::OptionsForSelect

def view_template
	# ❌ WRONG — the return value is a Never proxy; using it raises:
	select_tag :test, options_for_select([["Option 1", 1]])   # => Phlex::ArgumentError at render time

	# ✅ RIGHT — call it inside a block, output goes straight to the buffer:
	select_tag :test do
		options_for_select([["Option 1", 1], ["Option 2", 2]])
	end
end
```

--------------------------------

### GET /posts

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/endpoints.md

Renders the Views::Posts::Index component. When the X-Fragments header is present, only matching fragment blocks are returned.

```APIDOC
## GET /posts

### Description
Renders the `Views::Posts::Index` component. When the `X-Fragments` header is present, only matching fragment blocks are returned.

### Method
GET

### Endpoint
/posts

### Parameters
#### Request Headers
- **X-Fragments** (String) - Optional - Comma-separated fragment ids (e.g., "post_1, post_2"). When present, only the matching `fragment("id")` blocks of the rendered component are returned.

### Request Example
No request body.

### Response
#### Success Response (200)
- **Content-Type**: text/html
- **Body**: Rendered output of `Views::Posts::Index`, a `<div id="posts">` containing `fragment("post_1")` and `fragment("post_2")` blocks each wrapping a `<div id="post_N">` with an `<h1>` and a `<p>`.

#### Response Example (no header)
```html
<div id="posts">
	<div id="post_1">
		<h1>Post 1</h1>
		<p>This is the first post.</p>
	</div>
	<div id="post_2">
		<h1>Post 2</h1>
		<p>This is the second post.</p>
	</div>
</div>
```

#### Response Example (with `X-Fragments: post_1`)
```html
<div id="post_1">
	<h1>Post 1</h1>
	<p>This is the first post.</p>
</div>
```

### Status Codes
- **200** - Success (verified by `test/fragments.test.rb`). No error statuses are defined.

### Authentication
None - the test app has no authentication middleware.
```

--------------------------------

### Use Tag helper in a component

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/helpers.md

Example component that includes the Tag helper and uses tag.h1 and tag.img in a view template. Demonstrates the buffered builder pattern.

```ruby
include Phlex::Rails::Helpers::Tag

def view_template
	tag.h1(class: "title") { "Hello" }
	tag.img(src: "/logo.png")
end
```

--------------------------------

### app/components/base.rb template

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/configuration.md

Generated by `rails generate phlex:install`. Defines `Components::Base` inheriting from `Phlex::HTML`, includes `Phlex::Rails::Helpers::Routes` for all `*_path`/`*_url` helpers, and adds a development-only HTML comment before each template.

```ruby
class Components::Base < Phlex::HTML
  # Include any helpers you want to be available across all components
  include Phlex::Rails::Helpers::Routes

  if Rails.env.development?
    def before_template
      comment { "Before #{self.class.name}" }
      super
    end
  end
end
```

--------------------------------

### Route definition for GET /posts in config/quickdraw.rb

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/endpoints.md

Defines the only route in the repository, used by the test suite for full-stack rendering. The controller renders Views::Posts::Index.

```ruby
routes.append do
	resources :posts
end

class PostsController < ActionController::Base
	def index
		render Views::Posts::Index.new
	end
end
```

--------------------------------

### Fragment markup contract example from app/views/posts/index.rb

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/endpoints.md

Shows how to declare renderable fragments using Phlex's fragment method. The div#posts wraps two fragment blocks, each with a div#post_N containing an h1.

```ruby
def view_template
	div(id: "posts") do
		fragment("post_1") do
			div(id: "post_1") { h1 { "Post 1" } }
		end
	end
end
```

--------------------------------

### Block precedence example

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/partial.md

Shows that the block passed to render_in at render time overrides the construction-time block.

```ruby
p = Phlex::Rails::Partial.new("card") { h1 { "original" } }
p.render_in(view_context) { h1 { "override" } }   # renders with "override"
```

--------------------------------

### Usage - rendering a ViewComponent from Phlex

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/sgml.md

Example of rendering a ViewComponent from a Phlex view. The render method passes a block to the component, allowing the component to be configured before rendering.

```ruby
class BlogView < Phlex::HTML
	def view_template
		render BlogComponent.new(date: "Yesterday") do |blog|
			blog.with_header { plain "Hello" }
		end
	end
end
```

--------------------------------

### Use OptionsForSelect inside a select_tag block

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/helpers.md

Example component that includes SelectTag and OptionsForSelect helpers and calls options_for_select inside a select_tag block. This is the correct pattern to avoid the Phlex::ArgumentError.

```ruby
include Phlex::Rails::Helpers::SelectTag
include Phlex::Rails::Helpers::OptionsForSelect

def view_template
	select_tag :test do
		options_for_select([["Option 1", 1], ["Option 2", 2]])
	end
end
```

--------------------------------

### app/views/base.rb template

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/configuration.md

Generated by `rails generate phlex:install`. Defines `Views::Base` inheriting from `Components::Base` by default, and overrides `cache_store` to return `Rails.cache` so `cache` blocks use Rails' cache.

```ruby
class Views::Base < Components::Base
  # The `Views::Base` is an abstract class for all your views.

  # By default, it inherits from `Components::Base`, but you
  # can change that to `Phlex::HTML` if you want to keep views and
  # components independent.

  # More caching options at https://www.phlex.fun/components/caching
  def cache_store = Rails.cache
end
```

--------------------------------

### Non-trivial render_in usage from ERB

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/sgml.md

Example of rendering a component from an ERB template with a block that supplies nested template content.

```ruby
# In an .erb template:
<%= render NavComponent.new do |nav| %>
  <% nav.item("/") do %> Home <% end %>
<% end %>
```

--------------------------------

### Usage example for Translate helper with t method

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/helpers.md

Shows how to include the Translate helper and use the t method in a view template. Relative keys like ".title" are resolved against the class's translation_path, while absolute keys are delegated as-is.

```ruby
include Phlex::Rails::Helpers::Translate

def view_template
	h1 { t(".title") }        # resolves to "components.card.title" for Components::Card
	h1 { t("global.title") }  # absolute key delegated as-is
end
```

--------------------------------

### Usage example: Type(:link_builder) with Phlex::Rails.Buffered

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/types.md

Shows how to use the Buffered type constructor in Phlex's Types DSL to define a type for a tag builder attribute.

```ruby
Type(:link_builder) { Phlex::Rails.Buffered(ActionView::Helpers::TagHelper::TagBuilder) }
```

--------------------------------

### Full HTML response for GET /posts (no X-Fragments header)

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/endpoints.md

The complete rendered output of Views::Posts::Index when no X-Fragments header is present. Contains a div#posts wrapping two fragment blocks, each with an h1 and p.

```html
<div id="posts">
	<div id="post_1">
		<h1>Post 1</h1>
		<p>This is the first post.</p>
	</div>
	<div id="post_2">
		<h1>Post 2</h1>
		<p>This is the second post.</p>
	</div>
</div>
```

--------------------------------

### Usage example: Type(:form_builder) with Phlex::Rails.Builder

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/types.md

Shows how to use the Builder type constructor in Phlex's Types DSL to define a type for a form builder attribute.

```ruby
Type(:form_builder) { Phlex::Rails.Builder(ActionView::Helpers::FormBuilder) }
```

--------------------------------

### initialize

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/partial.md

Creates a new Phlex::Rails::Partial instance with the given path, arguments, keyword arguments, and block.

```APIDOC
## initialize

### Description
Creates a new Phlex::Rails::Partial instance that wraps a Rails partial path and optional locals/block.

### Method
initialize

### Parameters
#### Path Parameters
- `path` (String/Symbol) - Required - The Rails partial path (e.g. "card", "shared/hello").
- `args` (positional) - Optional - Positional arguments forwarded to `view_context.render`.
- `kwargs` (keyword args) - Optional - Locals forwarded to `view_context.render`.
- `block` (Proc) - Optional - Content block captured at construction time.

### Returns
The new `Partial` instance.

### Source
`lib/phlex/rails/partial.rb:4-9`
```

--------------------------------

### Rescue Phlex::ArgumentError from options_for_select misuse

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/errors.md

Example of rescuing Phlex::ArgumentError when using the return value of options_for_select as an argument to another helper. The error message starts with 'You can’t use the return value of options_for_select'.

```ruby
begin
	render component   # select_tag :test, options_for_select([...]) inside view_template
rescue Phlex::ArgumentError => e
	# e.message starts with "You can’t use the return value of options_for_select"
end
```

--------------------------------

### initialize

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/buffered.md

Creates a new Buffered instance wrapping the given object and associating it with a Phlex component for output capture.

```APIDOC
## initialize

### Description
Creates a new Buffered instance wrapping the given object and associating it with a Phlex component for output capture.

### Parameters
- `object` (Object) - Required - The wrapped object (e.g. `ActionView::Helpers::TagHelper::TagBuilder`, `Turbo::StreamsTagBuilder`).
- `component:` (Phlex::HTML subclass instance) - Required - The Phlex component that owns the output buffer; used for `raw`/`capture` calls.

### Returns
The new `Buffered` instance.

### Source
`lib/phlex/rails/buffered.rb:5-7`.
```

--------------------------------

### initialize

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/builder.md

Creates a new Builder instance wrapping a Rails builder object and a Phlex component for output buffering.

```APIDOC
## initialize

### Description
Creates a new Builder instance wrapping a Rails builder object and a Phlex component for output buffering.

### Parameters
- `object` (Object) - Required - The wrapped Rails builder instance.
- `component:` (Phlex::HTML subclass instance) - Required - The Phlex component owning the output buffer (used for `raw`).

### Returns
The new `Builder` instance.

### Source
`lib/phlex/rails/builder.rb:4-6`.
```

--------------------------------

### Usage — type-checking the wrapper

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/buffered.md

Demonstrates how to create a Buffered instance and inspect it. Shows that class is restored from Kernel, is_a? returns true, inspect returns a rough representation, unwrap returns the underlying TagBuilder, and respond_to?(:class) is delegated to TagBuilder.

```ruby
buffered = Phlex::Rails::Buffered.new(view_context.tag.div, component: component)
buffered.class          # => Phlex::Rails::Buffered   (restored from Kernel)
buffered.is_a?(Phlex::Rails::Buffered)  # => true
buffered.inspect        # => "Phlex::Rails::Buffered(<div></div>)" (roughly)
buffered.unwrap         # => the underlying TagBuilder
buffered.respond_to?(:class)  # => true (delegated to TagBuilder)
```

--------------------------------

### Builder usage example from test/types.test.rb

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/types.md

Shows how to use Phlex::Rails::Builder to check if a value is a builder-wrapped FormBuilder. The example creates a type predicate and tests it against a form builder and other values, expecting true for the builder and false for others.

```ruby
type = Phlex::Rails::Builder(ActionView::Helpers::FormBuilder)
ActionController::Base.new.view_context.form_with(url: "/", method: :get) do |form|
	type === Phlex::Rails::Builder.new(form, component: nil)   # => true
end
type === Phlex::Rails::Builder.new(nil, component: nil)        # => false
type === "not adapted builder"                                # => false
```

--------------------------------

### Usage - plain partial

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/partial.md

Shows how to render a Rails partial named 'hello' inside a Phlex component using the partial method.

```ruby
class Components::Card < Phlex::HTML
	def view_template
		div(class: "around") do
			render partial("hello")
		end
	end
end
```

--------------------------------

### Buffered usage example from test/types.test.rb

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/types.md

Shows how to use Phlex::Rails::Buffered to check if a value is a buffered TagBuilder. The example creates a type predicate and tests it against various values, expecting true for a buffered TagBuilder and false for others.

```ruby
type = Phlex::Rails::Buffered(ActionView::Helpers::TagHelper::TagBuilder)
tag = ActionController::Base.new.view_context.tag

type === Phlex::Rails::Buffered.new(tag, component: nil)  # => true
type === Phlex::Rails::Buffered.new(nil, component: nil)  # => false
type === "not buffered"                                   # => false
```

--------------------------------

### Basic render_in usage from Rails

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/sgml.md

Shows how Rails renders a component by calling render_in on the instance with the view context.

```ruby
render Components::Card.new   # controller → ActionView::Renderer → Component#render_in(view_context)
```

--------------------------------

### Define HelpersCalledBeforeRenderError

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/phlex-rails.md

Defines the HelpersCalledBeforeRenderError exception, raised when a Rails view helper is called before the component starts rendering.

```ruby
class HelpersCalledBeforeRenderError < StandardError; end
```

--------------------------------

### Class-level render_in usage

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/sgml.md

Examples of calling render_in at the class level: rendering an anonymous template component and a component instance.

```ruby
Phlex::HTML.render_in(view_context)            # renders an anonymous template component
Components::Card.render_in(view_context)       # renders a component instance
```

--------------------------------

### Phlex::Rails::HelpersCalledBeforeRenderError

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/errors.md

Raised when calling view_context before the component has started rendering. Rescue this error to handle render-time-only usage.

```APIDOC
## Phlex::Rails::HelpersCalledBeforeRenderError

### Description
Raised when calling `Phlex::Rails::SGML#view_context` when the component is not rendering (e.g., from an initializer, constructor, or after rendering finished).

### Type
`StandardError` subclass defined in `lib/phlex/rails.rb:7`.

### Trigger
Calling `view_context` when `rendering?` is false.

### Message
"You can’t use Rails view helpers until after the component has started rendering."

### Rescue Example
```ruby
component = Components::Card.new
begin
  component.view_context
rescue Phlex::Rails::HelpersCalledBeforeRenderError => e
  # use e.message to hint at render-time-only usage
end
```
```

--------------------------------

### register_output_helper

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/helper-macros.md

Generates an adapter method that delegates to the view_context method, captures blocks, and pushes the result to the output buffer with raw. Optionally marks the result as safe.

```APIDOC
## register_output_helper

### Description
Generates an adapter method that delegates to the Rails `view_context` method with the same name. If a block is given, it is captured via `capture` and passed to the view_context method. The result is pushed to the Phlex output buffer using `raw`. When `mark_safe` is `true`, the result is explicitly marked safe before being buffered.

### Method
Class method (macro)

### Signature
```ruby
def register_output_helper(method_name, mark_safe: false)
```

### Parameters
- **method_name** (Symbol) - Required - Name of the generated adapter method and the view_context method it delegates to.
- **mark_safe** (Boolean) - Optional, default `false` - When `true`, the delegated result is explicitly marked safe (`safe(output)`) before `raw`. When `false`, the raw output goes through Phlex's safety check and raises `Phlex::ArgumentError` if the helper returned an unsafe object.

### Returns (generated method)
The output-buffered result (returns the buffer, effectively `nil`-ish value pushed through `raw`).

### Generated Method Signature
```ruby
def link_to(*args, **kwargs, &block)
  output = if block
    view_context.link_to(*args, **kwargs) { |*args| capture(*args, &block) }
  else
    view_context.link_to(*args, **kwargs)
  end

  raw(output)
end
```

### Usage
```ruby
class Components::Base < Phlex::HTML
  register_output_helper :link_to
end

# inside view_template:
link_to "/posts" { "Posts" }
```

### Error Handling
When `mark_safe` is `false` (default), if the helper returns an unsafe object, `Phlex::ArgumentError` is raised. To fix, register with `mark_safe: true` when the helper returns raw HTML strings.

```ruby
view_ctx = ActionController::Base.new.view_context
view_ctx.define_singleton_method(:raw_html_producing_method) { "<span>ok</span>" }

component = Class.new(Phlex::HTML) do
  register_output_helper :raw_html_producing_method   # default mark_safe: false

  def view_template
    div { raw_html_producing_method }
  end
end

component.render_in(view_ctx)
# => Phlex::ArgumentError: "You passed an unsafe object to `raw`."

# Fix: register with mark_safe: true when the helper returns raw HTML strings
register_output_helper :raw_html_producing_method, mark_safe: true
```

### Source
`lib/phlex/rails/helper_macros.rb:5-20`
```

--------------------------------

### Reopen Phlex::HTML and Phlex::SVG classes

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/phlex-rails.md

Reopens both host classes to add SGML class methods, helper macros, and format methods. Every subclass automatically gains render_in, render, partial, view_context, capture_context, low_level_cache, set_original_view_context, enable_cache_reloading?, and method_missing helper guidance.

```ruby
class HTML
	extend Phlex::Rails::SGML::ClassMethods
	extend Phlex::Rails::HelperMacros

	include Phlex::Rails::SGML

	def self.format
		:html
	end

	def format
		:html
	end
end

class SVG
	extend Phlex::Rails::SGML::ClassMethods
	extend Phlex::Rails::HelperMacros

	include Phlex::Rails::SGML

	def self.format
		:svg
	end

	def format
		:svg
	end
end
```

--------------------------------

### view_context method implementation

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/sgml.md

Returns the Rails view context when rendering is active. Raises Phlex::Rails::HelpersCalledBeforeRenderError if called before rendering starts.

```ruby
def view_context
	if rendering?
		context[:rails_view_context]
	else
		raise Phlex::Rails::HelpersCalledBeforeRenderError.new(<<~MESSAGE)
			You can’t use Rails view helpers until after the component has started rendering.
		MESSAGE
	end
end
```

--------------------------------

### Output Helpers (110)

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/helpers.md

Each helper module defines a method that delegates to the corresponding Rails/Turbo helper. The result is pushed to the output buffer via raw. The table lists all 110 output helpers with their module names and method names.

```APIDOC
## Output Helpers (110)

### Description
Each helper module defines a method that delegates to the corresponding Rails/Turbo helper. The result is pushed to the output buffer via `raw`. The table below lists all 110 output helpers with their module names and method names.

### Helper Modules and Methods

| Module | Method | Rails/Turbo counterpart |
|--------|--------|--------------------------|
| ActionCableMetaTag | action_cable_meta_tag | [action_cable_meta_tag](https://api.rubyonrails.org/classes/ActionCable/Helpers/ActionCableHelper.html#method-i-action_cable_meta_tag) |
| AudioTag | audio_tag | [audio_tag](https://api.rubyonrails.org/classes/ActionView/Helpers/AssetTagHelper.html#method-i-audio_tag) |
| AutoDiscoveryLinkTag | auto_discovery_link_tag | [auto_discovery_link_tag](https://api.rubyonrails.org/classes/ActionView/Helpers/AssetTagHelper.html#method-i-auto_discovery_link_tag) |
| ButtonTag | button_tag | [button_tag](https://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html#method-i-button_tag) |
| ButtonTo | button_to | [button_to](https://api.rubyonrails.org/classes/ActionView/Helpers/UrlHelper.html#method-i-button_to) |
| Checkbox | checkbox | [checkbox](https://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-checkbox) |
| CheckboxTag | checkbox_tag | [checkbox_tag](https://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html#method-i-checkbox_tag) |
| CollectionSelect | collection_select | [collection_select](https://api.rubyonrails.org/classes/ActionView/Helpers/FormOptionsHelper.html#method-i-collection_select) |
| ColorField | color_field | [color_field](https://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-color_field) |
| ColorFieldTag | color_field_tag | [color_field_tag](https://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html#method-i-color_field_tag) |
| ContentTag | content_tag | [content_tag](https://api.rubyonrails.org/classes/ActionView/Helpers/TagHelper.html#method-i-content_tag) |
| CSPMetaTag | csp_meta_tag | [csp_meta_tag](https://api.rubyonrails.org/classes/ActionView/Helpers/CspHelper.html#method-i-csp_meta_tag) |
| CSRFMetaTags | csrf_meta_tags | [csrf_meta_tags](https://api.rubyonrails.org/classes/ActionView/Helpers/CsrfHelper.html#method-i-csrf_meta_tags) |
| DateField | date_field | [date_field](https://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-date_field) |
| DateFieldTag | date_field_tag | [date_field_tag](https://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html#method-i-date_field_tag) |
| DateSelect | date_select | [date_select](https://api.rubyonrails.org/classes/ActionView/Helpers/DateHelper.html#method-i-date_select) |
| DatetimeField | datetime_field | [datetime_field](https://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-datetime_field) |
| DatetimeFieldTag | datetime_field_tag | [datetime_field_tag](https://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html#method-i-datetime_field_tag) |
| DatetimeLocalField | datetime_local_field | [datetime_local_field](https://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-datetime_local_field) |
| DatetimeLocalFieldTag | datetime_local_field_tag | [datetime_local_field_tag](https://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html#method-i-datetime_local_field_tag) |
| DatetimeSelect | datetime_select | [datetime_select](https://api.rubyonrails.org/classes/ActionView/Helpers/DateHelper.html#method-i-datetime_select) |
| Debug | debug | [debug](https://api.rubyonrails.org/classes/ActionView/Helpers/DebugHelper.html#method-i-debug) |
| EmailField | email_field | [email_field](https://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-email_field) |
| EmailFieldTag | email_field_tag | [email_field_tag](https://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html#method-i-email_field_tag) |
| ErrorWrapping | error_wrapping | [error_wrapping](https://api.rubyonrails.org/classes/ActionView/Helpers/ActiveModelInstanceTag.html#method-i-error_wrapping) |
| FaviconLinkTag | favicon_link_tag | [favicon_link_tag](https://api.rubyonrails.org/classes/ActionView/Helpers/AssetTagHelper.html#method-i-favicon_link_tag) |
| FieldSetTag | field_set_tag | [field_set_tag](https://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html#method-i-field_set_tag) |
| FileField | file_field | [file_field](https://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-file_field) |
| FileFieldTag | file_field_tag | [file_field_tag](https://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html#method-i-file_field_tag) |
| FormTag | form_tag | [form_tag](https://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html#method-i-form_tag) |
```

--------------------------------

### CSV report with find_each streaming

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/csv.md

Example of a Phlex::CSV subclass that streams rows via find_each when the collection is an unordered relation. Uses routing helpers.

```ruby
class UsersReport < Phlex::CSV
	include Phlex::Rails::Helpers::Routes

	def view_template
		# each row is streamed via find_each when Users.all is an unordered relation
		rows Users.all do |user|
			row do
				cell user.id
				cell user.name
				cell user.email
			end
		end
	end
end
```

--------------------------------

### provide

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/helpers.md

Sets a content block for later use in the template. This helper is part of the CaptureHelper module.

```APIDOC
## provide

### Description
Sets a content block for later use in the template.

### Method
Helper method

### Source
[ActionView::Helpers::CaptureHelper#provide](https://api.rubyonrails.org/classes/ActionView/Helpers/CaptureHelper.html#method-i-provide)

### Returns
- **String** - The content block.
```

--------------------------------

### Define the OptionsForSelect helper module

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/helpers.md

Hand-written helper that buffers HTML output and returns a Phlex::Rails::Never proxy. Using the return value as a nested argument raises Phlex::ArgumentError; the correct pattern is to call it inside a block.

```ruby
module Phlex::Rails::Helpers::OptionsForSelect
	extend Phlex::Rails::HelperMacros

	# [Rails Docs](https://api.rubyonrails.org/classes/ActionView/Helpers/FormOptionsHelper.html#method-i-options_for_select)
	def options_for_select(*args, **kwargs, &block)
		output = if block
			view_context.options_for_select(*args, **kwargs) { |*args| capture(*args, &block) }
		else
			view_context.options_for_select(*args, **kwargs)
		end

		raw(output)

		Phlex::Rails::Never.new do
			raise Phlex::ArgumentError.new("You can’t use the return value of options_for_select as an argument to another helper in Phlex. …")
		end
	end
end
```

--------------------------------

### partial

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/sgml.md

Creates a Phlex::Rails::Partial instance, optionally capturing a block to be rendered inside the partial.

```APIDOC
## partial

### Description
Creates a Phlex::Rails::Partial instance, optionally capturing a block to be rendered inside the partial.

### Method
partial

### Parameters
- **\*** (positional args) - Required - Forwarded to `Partial#initialize` as the partial path and positional locals.
- **\*\*** (keyword args) - Required - Forwarded as partial locals.
- **block** (Proc) - Optional - When given, wrapped in a Phlex `capture` and stored on the `Partial`.

### Returns
A `Phlex::Rails::Partial` instance, designed to be passed to `render`.

### Usage
```ruby
def view_template
  div(class: "around") do
    render partial("card", title: "Hello") do
      h3 { "Hello from inside" }
    end
  end
end
```

### Source
`lib/phlex/rails/sgml.rb:37-43`.
```

--------------------------------

### Rescue HelpersCalledBeforeRenderError

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/errors.md

Example of rescuing Phlex::Rails::HelpersCalledBeforeRenderError when calling view_context outside rendering. The class is defined before Zeitwerk loads, so it is always available after require "phlex/rails".

```ruby
component = Components::Card.new
begin
	component.view_context
rescue Phlex::Rails::HelpersCalledBeforeRenderError => e
	# use e.message to hint at render-time-only usage
end
```

--------------------------------

### Rendering a Phlex component from a ViewComponent

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/sgml.md

Shows how to render a Phlex component from a ViewComponent. The ViewComponent becomes the capture_context, so capture and buffer target the ViewComponent's output buffer automatically.

```ruby
# Rendering a Phlex component from a ViewComponent: the ViewComponent becomes capture_context,
# so `capture` and `buffer` target the ViewComponent's output buffer automatically.
render(NavComponent.new)
```

--------------------------------

### Configure Zeitwerk loader for Phlex::Rails

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/phlex-rails.md

Sets up the Zeitwerk gem-extension loader for the Phlex namespace, ignoring the ruby_lsp directory, applying custom inflections for Rails helper names, and collapsing the errors directory.

```ruby
Loader = Zeitwerk::Loader.for_gem_extension(Phlex).tap do |loader|
	loader.ignore("#{__dir__}/ruby_lsp")

	loader.inflector.inflect(
		"asset_url" => "AssetURL",
		"audio_url" => "AudioURL",
		"csp_meta_tag" => "CSPMetaTag",
		"csrf_meta_tags" => "CSRFMetaTags",
		"csv" => "CSV",
		"default_url_options" => "DefaultURLOptions",
		"dom_class" => "DOMClass",
		"dom_id" => "DOMID",
		"field_id" => "FieldID",
		"font_url" => "FontURL",
		"image_url" => "ImageURL",
		"javascript_import_module_tag" => "JavaScriptImportModuleTag",
		"javascript_importmap_module_preload_tags" => "JavaScriptImportmapModulePreloadTags",
		"javascript_importmap_tags" => "JavaScriptImportmapTags",
		"javascript_include_tag" => "JavaScriptIncludeTag",
		"javascript_inline_importmap_tag" => "JavaScriptInlineImportmapTag",
		"javascript_path" => "JavaScriptPath",
		"javascript_tag" => "JavaScriptTag",
		"javascript_url" => "JavaScriptURL",
		"path_to_javascript" => "PathToJavaScript",
		"path_to_stylesheet" => "PathToStyleSheet",
		"rich_textarea" => "RichTextArea",
		"sanitize_css" => "SanitizeCSS",
		"sgml" => "SGML",
		"sms_to" => "SMSTo",
		"stylesheet_link_tag" => "StyleSheetLinkTag",
		"stylesheet_path" => "StyleSheetPath",
		"stylesheet_url" => "StyleSheetURL",
		"textarea" => "TextArea",
		"textarea_tag" => "TextAreaTag",
		"url_field" => "URLField",
		"url_field_tag" => "URLFieldTag",
		"url_for" => "URLFor",
		"url_options" => "URLOptions",
		"url_to_asset" => "URLToAsset",
		"url_to_audio" => "URLToAudio",
		"url_to_font" => "URLToFont",
		"url_to_image" => "URLToImage",
		"url_to_javascript" => "URLToJavaScript",
		"url_to_stylesheet" => "URLToStyleSheet",
		"url_to_video" => "URLToVideo",
		"utf8_enforcer_tag" => "UTF8EnforcerTag",
		"video_url" => "VideoURL",
	)

	loader.collapse("#{__dir__}/phlex/errors")
	loader.setup
end
```

--------------------------------

### Usage of register_output_helper with link_to

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/helper-macros.md

Shows how to register the link_to helper in a Phlex component and use it inside view_template. The generated method delegates to Rails view_context and buffers the output.

```ruby
class Components::Base < Phlex::HTML
	register_output_helper :link_to
end

# inside view_template:
link_to "/posts" { "Posts" }
```

--------------------------------

### Render layout from controller with class or instance

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/layout.md

Shows two ways to pass the layout to render: using the class itself (Components::Layout) or an instance (Components::Layout.new). Both are valid forms.

```ruby
# render(Components::Layout) — class form
render "hello", layout: Components::Layout

# render(Components::Layout.new) — instance form
render "hello", layout: Components::Layout.new
```

--------------------------------

### Usage - partial with locals and a block

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/partial.md

Demonstrates rendering a partial with locals and a block. The partial receives a title local and yields to the block content. The ERB template shows how to use the title and yield. The output shows the rendered HTML.

```ruby
def view_template
	div do
		render partial("card", title: "Hello") do
			h3 { "Hello from inside" }
		end
	end
end
```

```erb
<%# app/views/_card.html.erb %>
<article>
  <h1><%= title %></h1>
  <%= yield %>
</article>
```

```html
<div>
	<article>
		<h1>Hello</h1>
		<h3>Hello from inside</h3>
	</article>
</div>
```

--------------------------------

### Render Phlex component from Rails controller

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/phlex-rails.md

Shows how to render a Phlex component from a Rails controller using the normal render API, passing the component instance to render.

```ruby
class PostsController < ActionController::Base
	def show
		render Components::Card.new
	end
end
```

--------------------------------

### Type check with Buffered in Types DSL

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/buffered.md

Use Buffered(ActionView::Helpers::TagHelper::TagBuilder) in a Types predicate to match values where the wrapper and unwrapped object match. The example shows a view template where tag returns a Buffered TagBuilder and the helper call is buffered.

```ruby
Type(:tag_builder) { Buffered(ActionView::Helpers::TagHelper::TagBuilder) }

def view_template
	div do
		# tag returns a Buffered TagBuilder; the helper call is buffered, the
		# returned proxy can be safely ignored or passed to typed APIs.
		h1 { "Hi" }
	end
end
```

--------------------------------

### Define the Routes helper module

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/helpers.md

Hand-written module that includes all Rails URL helpers and must be included first so its url_options wins over delegation. It pulls in all generated *_path/*_url and mounted-helper methods from Rails.application.routes.

```ruby
module Phlex::Rails::Helpers
	module Routes
		# This must be included first because it defines `url_options` rather than delegating it to the view context.
		include Rails.application.routes.url_helpers
		include Rails.application.routes.mounted_helpers

		include URLOptions
		include DefaultURLOptions
	end
end
```

--------------------------------

### activate method (empty)

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/ruby-lsp-addon.md

The activate method is a no-op. Called by Ruby LSP on activation.

```ruby
def activate(global_state, message_queue)
end
```

--------------------------------

### Expected HTML output from layout

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/layout.md

The resulting HTML output from test/layouts.test.rb, showing the header and main sections with the yielded content.

```html
<header>
	<h1>Content for header</h1>
</header>
<main>
	<h1>Hello</h1>
</main>
```

--------------------------------

### Generated method signature for register_output_helper

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/helper-macros.md

Shows the method that register_output_helper generates for a helper like link_to. It delegates to view_context, captures blocks, and pushes the result through raw.

```ruby
def link_to(*args, **kwargs, &block)
	output = if block
		view_context.link_to(*args, **kwargs) { |*args| capture(*args, &block) }
	else
		view_context.link_to(*args, **kwargs)
	end

	raw(output)
end
```

--------------------------------

### InstallGenerator Ruby class

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/generators.md

Defines the Rails generator that creates config/initializers/phlex.rb, app/components/base.rb, and app/views/base.rb from templates. The templates are located in lib/generators/phlex/install/templates/.

```ruby
module Phlex::Generators
	class InstallGenerator < ::Rails::Generators::Base
		source_root File.expand_path("templates", __dir__)

		def create_initializer
			template "phlex.rb.erb", File.join(destination_root, "config/initializers/phlex.rb")
		end

		def create_base_component
			template "base_component.rb.erb", File.join(destination_root, "app/components/base.rb")
		end

		def create_base_view
			template "base_view.rb.erb", File.join(destination_root, "app/views/base.rb")
		end
	end
end
```

--------------------------------

### register_output_helper macro implementation

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/helper-macros.md

Defines the register_output_helper class method that generates an adapter method delegating to view_context. The generated method captures blocks via capture and pushes the result to the output buffer with raw. The mark_safe parameter controls whether the result is explicitly marked safe before raw.

```ruby
def register_output_helper(method_name, mark_safe: false)
	class_eval(<<-RUBY, __FILE__, __LINE__ + 1)
		# frozen_string_literal: true

		def #{method_name}(*args, **kwargs, &block)
			output = if block
				view_context.#{method_name}(*args, **kwargs) { |*args| capture(*args, &block) }
			else
				view_context.#{method_name}(*args, **kwargs)
			end

			raw(#{mark_safe ? 'safe(output)' : 'output'})
		end
	RUBY
end
```

--------------------------------

### render instance method: render with view context and content_for support

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/layout.md

Defines the render method for Phlex::Rails::Layout. If the component has already been rendered (@_state set), delegates to super. Otherwise renders through render_in(view_context) and handles yielded symbols as content_for names via view_context.view_flow.get, forwarding other yields to the component's yield. Source: lib/phlex/rails/layout.rb:50-63.

```ruby
def render(view_context = nil, *args, **kwargs, &block)
	if @_state
		super
	else
		render_in(view_context) do |yielded|
			case yielded
			when Symbol
				raw view_context.view_flow.get(yielded)
			else
				yield
			end
		end
	end
end
```

--------------------------------

### Include Phlex::Rails helpers in a component base class

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/helpers.md

Shows the recommended way to include the Routes, LinkTo, ContentTag, and FormWith helpers into a base component class. Missing includes are caught at render time with a NoMethodError that names the required module.

```ruby
class Components::Base < Phlex::HTML
	include Phlex::Rails::Helpers::Routes            # routing helpers (see below)
	include Phlex::Rails::Helpers::LinkTo
	include Phlex::Rails::Helpers::ContentTag
	include Phlex::Rails::Helpers::FormWith
end
```

--------------------------------

### partial method implementation

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/sgml.md

Creates a Phlex::Rails::Partial instance. If a block is given, it is captured and stored on the Partial; otherwise the Partial is created without a block.

```ruby
def partial(*, **, &block)
	if block
		Phlex::Rails::Partial.new(*, **) { capture(&block) }
	else
		Phlex::Rails::Partial.new(*, **)
	end
end
```

--------------------------------

### Usage — tag builder

Source: https://github.com/yippee-fun/phlex-rails/blob/main/_autodocs/api-reference/buffered.md

Shows how to include the Tag helper and use tag.div to create a Buffered TagBuilder. Chained calls like .class return new Buffered wrappers whose output flows through the component's buffer.

```ruby
include Phlex::Rails::Helpers::Tag

def view_template
	# tag.div returns a Buffered(TagBuilder); chained calls like .class return
	# new Buffered wrappers whose output flows through the component's buffer.
	tag.div(class: "card") do
		tag.h1 { "Hello" }
	end
end
```
Tokens:
Raw