plutonium 0.23.5 → 0.24.1

data/docs/modules/form.md

@@ -4,278 +4,329 @@ title: Form Module
 
 # Form Module
 
-The Form module provides a comprehensive form building system for Plutonium applications. Built on top of `Phlexi::Form`, it offers enhanced input components, automatic field inference, secure associations, and modern UI interactions for creating rich, accessible forms.
+The Form module is Plutonium's comprehensive system for building powerful, modern, and secure forms. It extends the `Phlexi::Form` library to provide a suite of enhanced input components, automatic field inference, secure-by-default associations, and seamless integration with your resources. This module is designed to make creating rich, accessible, and interactive forms a breeze.
 
 ::: tip
 The Form module is located in `lib/plutonium/ui/form/`.
 :::
 
-## Overview
+## Key Features
 
-- **Enhanced Input Components**: Rich input types with JavaScript integration.
-- **Secure Associations**: SGID-based association handling with authorization.
-- **Type Inference**: Automatic component selection based on field types.
-- **Resource Integration**: Seamless integration with resource definitions.
-- **Modern UI**: File uploads, date pickers, rich text editors, and more.
-- **Accessibility**: ARIA-compliant forms with keyboard navigation.
+- **Rich Input Components**: Out-of-the-box support for markdown editors, date pickers, file uploads with previews, and international phone inputs.
+- **Secure by Default**: All associations use Signed Global IDs (SGIDs) to prevent parameter tampering, with automatic authorization checks.
+- **Intelligent Type Inference**: Automatically selects the best input component based on Active Record column types, saving you from boilerplate.
+- **Deep Resource Integration**: Generate forms automatically from your resource definitions, including support for conditional fields.
+- **Modern Frontend**: A complete theme system built with Tailwind CSS, Stimulus for interactivity, and first-class dark mode support.
+- **Complex Form Structures**: Easily manage associations with nested forms supporting dynamic "add" and "remove" functionality.
 
-## Core Components
+## Core Form Classes
 
-### Base Form (`lib/plutonium/ui/form/base.rb`)
+Plutonium provides several base form classes, each tailored for a specific purpose.
 
-This is the foundation that all Plutonium form components inherit from. It extends `Phlexi::Form::Base` with Plutonium's specific behaviors and custom input components.
+### `Form::Base`
+
+This is the foundation for all forms in Plutonium. It extends `Phlexi::Form::Base` and includes the core form builder with all the custom input components. You can inherit from this class to create custom, one-off forms.
+
+::: details Builder Implementation
+The `Builder` class within `Form::Base` is where all the custom input tag methods are defined. It aliases standard Rails form helpers like `belongs_to_tag` to Plutonium's secure and enhanced versions.
 
-::: details Base Form Implementation
 ```ruby
 class Plutonium::UI::Form::Base < Phlexi::Form::Base
-  include Plutonium::UI::Component::Behaviour
-
-  # Enhanced builder with Plutonium-specific components
+  # ...
   class Builder < Builder
     include Plutonium::UI::Form::Options::InferredTypes
 
-    def easymde_tag(**options, &block)
-      create_component(Plutonium::UI::Form::Components::Easymde, :easymde, **options, &block)
-    end
+    # Enhanced input components
+    def easymde_tag(**); end
     alias_method :markdown_tag, :easymde_tag
 
-    def flatpickr_tag(**options, &block)
-      create_component(Components::Flatpickr, :flatpickr, **options, &block)
-    end
+    def flatpickr_tag(**); end
+    def int_tel_input_tag(**); end
+    alias_method :phone_tag, :int_tel_input_tag
 
-    def uppy_tag(**options, &block)
-      create_component(Components::Uppy, :uppy, **options, &block)
-    end
+    def uppy_tag(**); end
     alias_method :file_tag, :uppy_tag
     alias_method :attachment_tag, :uppy_tag
 
-    def secure_association_tag(**attributes, &block)
-      create_component(Components::SecureAssociation, :association, **attributes, &block)
-    end
+    def slim_select_tag(**); end
+    def secure_association_tag(**); end
+    def secure_polymorphic_association_tag(**); end
 
-    # Override default association methods to use secure versions
+    # Override default association methods
     alias_method :belongs_to_tag, :secure_association_tag
     alias_method :has_many_tag, :secure_association_tag
     alias_method :has_one_tag, :secure_association_tag
+    alias_method :polymorphic_belongs_to_tag, :secure_polymorphic_association_tag
   end
 end
 ```
 :::
 
-### Resource Form (`lib/plutonium/ui/form/resource.rb`)
+### `Form::Resource`
 
-This is a specialized form for resource objects that automatically renders fields based on the resource's definition, handling nested resources and actions gracefully.
+This is a specialized form that intelligently renders inputs based on a resource definition. It's the primary way you'll create `new` and `edit` forms for your models. It automatically handles field rendering, nested resources, and conditional logic defined in your resource class.
 
 ```ruby
-class PostForm < Plutonium::UI::Form::Resource
-  def initialize(post, resource_definition:)
-    super(post, resource_definition: resource_definition)
+class Plutonium::UI::Form::Resource < Base
+  include Plutonium::UI::Form::Concerns::RendersNestedResourceFields
+
+  def initialize(object, resource_fields:, resource_definition:, **options)
+    # ...
   end
 
   def form_template
-    render_resource_fields    # Render configured input fields
-    render_nested_resources   # Render nested associations
-    render_actions           # Render submit/cancel buttons
+    render_fields    # Renders inputs from resource_definition
+    render_actions   # Renders submit/cancel buttons
+  end
+end
+```
+
+### `Form::Query`
+
+This form is built for search and filtering. It integrates with Plutonium's Query Objects to create search inputs, dynamic filter controls, and hidden fields for sorting and pagination, all submitted via GET requests to preserve filterable URLs.
+
+```ruby
+class Plutonium::UI::Form::Query < Base
+  def initialize(object, query_object:, page_size:, **options)
+    # ... configured as a GET form with Turbo integration
+  end
+
+  def form_template
+    render_search_fields
+    render_filter_fields
+    render_sort_fields
+    render_scope_fields
+  end
+end
+```
+
+### `Form::Interaction`
+
+This specialized form is designed for handling user interactions and actions. It automatically configures itself based on an interaction object, setting up the appropriate fields and form behavior for interactive actions.
+
+```ruby
+class Plutonium::UI::Form::Interaction < Resource
+  def initialize(interaction, **options)
+    # Automatically configures fields from interaction attributes
+    options[:resource_fields] = interaction.attribute_names.map(&:to_sym) - %i[resource resources]
+    options[:resource_definition] = interaction
+    # ...
+  end
+
+  # Form posts to the same page for interaction handling
+  def form_action
+    nil
   end
 end
 ```
 
 ## Enhanced Input Components
 
-### Rich Text Editor (Easymde)
+Plutonium replaces standard form inputs with enhanced versions that provide a modern user experience.
+
+### Input Block Syntax
 
-A client-side markdown editor with live preview, based on [EasyMDE](https://github.com/Ionaru/easy-markdown-editor).
+Input blocks provide additional flexibility for custom logic while ensuring proper form integration. **Important**: Input blocks can only use existing form builder methods (like `date_tag`, `text_tag`, etc.) because the form system requires inputs to be registered internally.
 
 ::: code-group
-```ruby [Basic Usage]
-# Automatically used for :markdown fields
-render field(:content).easymde_tag
+```ruby [Input Block Example]
+# Valid: Using form builder methods with custom logic
+input :birth_date do |f|
+  case object.age_category
+  when 'adult'
+    f.date_tag(min: 18.years.ago.to_date)
+  when 'minor'
+    f.date_tag(max: 18.years.ago.to_date)
+  else
+    f.date_tag
+  end
+end
 ```
 
-```ruby [With Options]
-render field(:description).easymde_tag(
-  toolbar: ["bold", "italic", "heading", "|", "quote"],
-  spellChecker: false,
-  autosave: { enabled: true, uniqueId: "post_content" }
-)
+```ruby [Custom Component Classes]
+# New: Pass component classes directly to as: option
+# Works for both input and display
+input :color_picker, as: ColorPickerComponent
+input :custom_slider, as: RangeSliderComponent
+
+display :status_badge, as: StatusBadgeComponent
+display :progress_chart, as: ProgressChartComponent
 ```
 :::
 
-### Date/Time Picker (Flatpickr)
+### Markdown Editor (Easymde)
 
-A powerful and lightweight date and time picker from [Flatpickr](https://flatpickr.js.org/).
+For rich text content, Plutonium integrates a client-side markdown editor based on [EasyMDE](https://github.com/Ionaru/easy-markdown-editor). It's automatically used for `rich_text` fields (like ActionText) and provides a live preview.
 
 ::: code-group
-```ruby [Date Picker]
-# Automatically used for :date fields
-render field(:published_at).flatpickr_tag
-```
-```ruby [Time Picker]
-# Automatically used for :time fields
-render field(:meeting_time).flatpickr_tag
-```
-```ruby [Datetime Picker]
-# Automatically used for :datetime fields
-render field(:deadline).flatpickr_tag
-```
-```ruby [With HTML Attributes]
-render field(:event_date).flatpickr_tag(
-  class: "custom-date-picker",
-  placeholder: "Select date..."
-)
+```ruby [Automatic Usage]
+# Automatically used for ActionText rich_text fields
+render field(:content).easymde_tag
+
+# Or explicitly with an alias
+render field(:description).markdown_tag
 ```
 :::
 
-::: warning Flatpickr Configuration
-The current implementation uses automatic configuration based on field type:
-- **Date fields**: Basic date picker with `altInput: true`
-- **Time fields**: Time picker with `enableTime: true, noCalendar: true`
-- **Datetime fields**: Date and time picker with `enableTime: true`
+::: details Component Internals
+The component renders a `textarea` with a `data-controller="easymde"` attribute. It also includes logic to correctly handle ActionText objects by calling `to_plain_text` on the value.
 
-Custom Flatpickr options (like `dateFormat`, `mode: "range"`) are not currently supported through tag attributes.
+```ruby
+class Plutonium::UI::Form::Components::Easymde < Phlexi::Form::Components::Base
+  def view_template
+    textarea(**attributes, data_controller: "easymde") do
+      normalize_value(field.value)
+    end
+  end
+  # ...
+end
+```
 :::
 
-### File Upload (Uppy)
+### Date/Time Picker (Flatpickr)
 
-A sleek, modern file uploader powered by [Uppy](https://uppy.io/).
+A beautiful and lightweight date/time picker from [Flatpickr](https://flatpickr.js.org/). It's automatically enabled for `date`, `time`, and `datetime` fields.
 
 ::: code-group
-```ruby [Single File]
-# Automatically used for :file or :attachment fields
-render field(:avatar).uppy_tag
-```
-```ruby [Multiple Files]
-render field(:documents).uppy_tag(multiple: true)
+```ruby [Automatic Usage]
+# Automatically used based on field type
+render field(:published_at).flatpickr_tag  # datetime field
+render field(:event_date).flatpickr_tag    # date field
+render field(:meeting_time).flatpickr_tag  # time field
 ```
-```ruby [With Restrictions]
-render field(:gallery).uppy_tag(
-  multiple: true,
-  allowed_file_types: ['.jpg', '.jpeg', '.png'],
-  max_file_size: 5.megabytes
-)
+:::
+
+::: details Component Internals
+The component simply adds a `data-controller="flatpickr"` attribute to a standard input. The corresponding Stimulus controller then inspects the input's `type` attribute (`date`, `time`, or `datetime-local`) to initialize Flatpickr with the correct options (e.g., with or without the time picker).
+
+```ruby
+class Plutonium::UI::Form::Components::Flatpickr < Phlexi::Form::Components::Input
+  private
+
+  def build_input_attributes
+    super
+    attributes[:data_controller] = tokens(attributes[:data_controller], :flatpickr)
+  end
+end
 ```
-```ruby [Direct to Cloud]
-render field(:videos).uppy_tag(
-  direct_upload: true, # For S3, etc.
-  max_total_size: 100.megabytes
-)
+:::
+
+### International Phone Input
+
+For phone numbers, a user-friendly input with a country-code dropdown is provided by [intl-tel-input](https://github.com/jackocnr/intl-tel-input).
+
+::: code-group
+```ruby [Usage]
+# Automatically used for fields of type :tel
+render field(:phone).int_tel_input_tag
+
+# Or using its alias
+render field(:mobile).phone_tag
 ```
 :::
 
-::: details Uppy Component Implementation
-The Uppy component automatically handles rendering existing attachments and providing an interface to upload new ones.
-```ruby
-class Plutonium::UI::Form::Components::Uppy
-  # Automatic features:
-  # - Drag and drop upload
-  # - Progress indicators
-  # - Image previews and thumbnails
-  # - File type and size validation
-  # - Direct-to-cloud upload support
-  # - Interactive preview and deletion of existing attachments
+::: details Component Internals
+This component wraps the input in a `div` with a `data-controller="intl-tel-input"` and adds a `data_intl_tel_input_target` to the input itself, allowing the Stimulus controller to initialize the library.
 
+```ruby
+class Plutonium::UI::Form::Components::IntlTelInput < Phlexi::Form::Components::Input
   def view_template
-    div(class: "flex flex-col-reverse gap-2") do
-      render_existing_attachments
-      render_upload_interface
+    div(data_controller: "intl-tel-input") do
+      super # Renders the input with proper data targets
     end
   end
 
   private
 
-  def render_existing_attachments
-    Array(field.value).each do |attachment|
-      render_attachment_preview(attachment)
-    end
-  end
-
-  def render_attachment_preview(attachment)
-    # Interactive preview with delete option
-    div(class: "attachment-preview", data: { controller: "attachment-preview" }) do
-      render_thumbnail(attachment)
-      render_filename(attachment)
-      render_delete_button
-    end
+  def build_input_attributes
+    super
+    attributes[:data_intl_tel_input_target] = tokens(attributes[:data_intl_tel_input_target], :input)
   end
 end
 ```
 :::
 
-### International Phone Input
+### File Upload (Uppy)
 
-A user-friendly phone number input with country code selection, using [intl-tel-input](https://github.com/jackocnr/intl-tel-input).
+File uploads are handled by [Uppy](https://uppy.io/), a sleek, modern uploader. It supports drag & drop, progress indicators, direct-to-cloud uploads, and interactive previews for existing attachments.
 
 ::: code-group
 ```ruby [Basic Usage]
-# Automatically used for :tel fields
-render field(:phone).int_tel_input_tag
-```
-```ruby [Phone Tag Alias]
-# Alias for int_tel_input_tag
-render field(:mobile).phone_tag
+# Automatically used for file and Active Storage attachments
+render field(:avatar).uppy_tag
+render field(:documents).file_tag     # alias
+render field(:gallery).attachment_tag # alias
 ```
-```ruby [With HTML Attributes]
-render field(:contact_phone).int_tel_input_tag(
-  class: "custom-phone-input",
-  placeholder: "Enter phone number"
+
+```ruby [With Options]
+render field(:documents).uppy_tag(
+  multiple: true,
+  direct_upload: true, # For S3, etc.
+  max_file_size: 10.megabytes,
+  allowed_file_types: ['.pdf', '.doc']
 )
 ```
 :::
 
-::: warning Int Tel Input Configuration
-The current implementation uses a fixed configuration:
-- **Strict Mode**: Enabled for validation
-- **Utils Loading**: Automatically loads validation utilities
-- **Hidden Input**: Creates hidden field for form submission
+::: details Component Internals
+The Uppy component is quite sophisticated. It renders an interactive preview grid for existing attachments (each with its own `attachment-preview` Stimulus controller for deletion) and a file input managed by an `attachment-input` Stimulus controller that initializes Uppy.
+
+```ruby
+class Plutonium::UI::Form::Components::Uppy < Phlexi::Form::Components::Input
+  # Automatic features:
+  # - Interactive preview of existing attachments
+  # - Delete buttons for removing attachments
+  # - Support for direct cloud uploads
+  # - File type and size validation via Uppy options
+  # ...
 
-Custom intl-tel-input options (like `onlyCountries`, `preferredCountries`) are not currently supported through tag attributes.
+  def view_template
+    div(class: "flex flex-col-reverse gap-2") do
+      render_existing_attachments
+      render_upload_interface
+    end
+  end
+end
+```
 :::
 
 ### Secure Association Inputs
 
-Plutonium's association inputs are secure by default, using SGIDs to prevent parameter tampering and scoping options based on user authorization.
+Plutonium overrides all standard Rails association helpers (`belongs_to`, `has_many`, etc.) to use a secure, enhanced version that integrates with [SlimSelect](https://slimselectjs.com/) for a better UI.
 
 ::: code-group
-```ruby [Belongs To]
-# Automatically used for belongs_to associations
+```ruby [Association Types]
+# Automatically used for all standard association types
 render field(:author).belongs_to_tag
-```
-```ruby [Has Many]
-# Automatically used for has_many associations
 render field(:tags).has_many_tag
+render field(:profile).has_one_tag
+render field(:commentable).polymorphic_belongs_to_tag
 ```
-```ruby [With Custom Choices]
+
+```ruby [With Options]
 render field(:category).belongs_to_tag(
-  choices: Category.published.pluck(:name, :id)
-)
-```
-```ruby [With Add Action]
-render field(:publisher).belongs_to_tag(
-  add_action: new_publisher_path
+  choices: Category.published.pluck(:name, :id),
+  add_action: new_category_path, # Adds a "+" button to add new records
+  skip_authorization: false      # Enforces authorization policies
 )
 ```
 :::
 
-::: details Secure Association Implementation
+::: details Security & Implementation
+The `SecureAssociation` component is the cornerstone of Plutonium's form security.
+- **SGID Encoding**: It uses `to_signed_global_id` as the value method, so raw database IDs are never exposed to the client.
+- **Authorization**: It uses `authorized_resource_scope` to ensure that the choices presented to the user are only the ones they are permitted to see.
+- **Add Action**: It can render an "add new" button that automatically includes a `return_to` parameter for a smooth UX.
+
 ```ruby
 class Plutonium::UI::Form::Components::SecureAssociation
-  # Automatic features:
-  # - SGID-based value encoding for security.
-  # - Authorization checks before showing options.
-  # - "Add new record" button with `return_to` handling.
-  # - Polymorphic association support.
-  # - Search and filtering (via SlimSelect).
-
   def choices
     collection = if @skip_authorization
-      choices_from_association(association_reflection.klass)
+      # ...
     else
       # Only show records user is authorized to see
-      authorized_resource_scope(
-        association_reflection.klass,
-        with: @scope_with,
-        context: @scope_context
-      )
+      authorized_resource_scope(association_reflection.klass,
+                               relation: choices_from_association(association_reflection.klass))
     end
     # ...
   end
@@ -283,29 +334,13 @@ end
 ```
 :::
 
-## Type Inference
-
-### Automatic Component Selection (`lib/plutonium/ui/form/options/inferred_types.rb`)
+## Type Inference System
 
-The system automatically selects appropriate input components:
+Plutonium is smart about choosing the right input for a given field, minimizing boilerplate in your forms.
 
-```ruby
-# Automatic inference based on Active Record column types
-render field(:title).input_tag          # → input_tag (string)
-render field(:content).easymde_tag        # → easymde_tag (text/rich_text)
-render field(:published_at).flatpickr_tag   # → flatpickr_tag (datetime)
-render field(:author).secure_association_tag         # → secure_association_tag (belongs_to)
-render field(:featured_image).uppy_tag # → uppy_tag (Active Storage)
-render field(:category).slim_select_tag       # → slim_select_tag (select)
-
-# Manual override
-render field(:title).input_tag(as: :string)
-render field(:content).easymde_tag
-render field(:published_at).flatpickr_tag
-render field(:documents).uppy_tag(multiple: true)
-```
+### Automatic Component Selection
 
-### Type Mapping
+The `InferredTypes` module overrides the default type inference to map common types to Plutonium's enhanced components.
 
 ```ruby
 module Plutonium::UI::Form::Options::InferredTypes
@@ -314,292 +349,147 @@ module Plutonium::UI::Form::Options::InferredTypes
   def infer_field_component
     case inferred_field_type
     when :rich_text
-      :markdown  # Use EasyMDE for rich text
+      return :markdown  # Use Easymde for ActionText fields
     end
 
-    inferred_component = super
-    case inferred_component
+    inferred = super
+    case inferred
     when :select
-      :slim_select  # Enhance selects with SlimSelect
+      :slim_select    # Enhance selects with SlimSelect
     when :date, :time, :datetime
-      :flatpickr   # Use Flatpickr for date/time
+      :flatpickr     # Use Flatpickr for date/time fields
     else
-      inferred_component
+      inferred
     end
   end
 end
 ```
 
-## Theme System
-
-### Form Theme (`lib/plutonium/ui/form/theme.rb`)
-
-Comprehensive theming for consistent form appearance:
+This means you often don't need to specify the input type at all.
 
 ```ruby
-class Plutonium::UI::Form::Theme < Phlexi::Form::Theme
-  def self.theme
-    super.merge({
-      # Layout
-      fields_wrapper: "space-y-6",
-      actions_wrapper: "flex justify-end space-x-3 pt-6 border-t",
+# These are automatically inferred:
+render field(:title)          # -> input (string)
+render field(:content)        # -> easymde (rich_text)
+render field(:published_at)   # -> flatpickr (datetime)
+render field(:phone)          # -> int_tel_input (tel)
+render field(:author)         # -> secure_association (belongs_to)
+render field(:avatar)         # -> uppy (Active Storage attachment)
+render field(:category)       # -> slim_select (enum/select)
+```
 
-      # Input styles
-      input: "w-full border rounded-md shadow-sm px-3 py-2 border-gray-300 dark:border-gray-600 focus:ring-primary-500 focus:border-primary-500",
-      textarea: "w-full border rounded-md shadow-sm px-3 py-2 border-gray-300 dark:border-gray-600 focus:ring-primary-500 focus:border-primary-500",
-      select: "w-full border rounded-md shadow-sm px-3 py-2 border-gray-300 dark:border-gray-600 focus:ring-primary-500 focus:border-primary-500",
+## Nested Resources
 
-      # Enhanced components
-      flatpickr: :input,
-      int_tel_input: :input,
-      easymde: "w-full border rounded-md border-gray-300 dark:border-gray-600",
-      uppy: "w-full border rounded-md border-gray-300 dark:border-gray-600",
+Plutonium has first-class support for `accepts_nested_attributes_for`, allowing you to build complex forms with nested records. This is handled by the `RendersNestedResourceFields` concern in `Form::Resource`.
 
-      # Association components
-      association: :select,
+### Defining Nested Inputs
 
-      # File input
-      file: "w-full border rounded-md shadow-sm font-medium text-sm border-gray-300 dark:border-gray-600",
+You define nested inputs in your resource definition file. Plutonium will automatically detect the configuration from your Rails model's `accepts_nested_attributes_for` declaration—including options like `allow_destroy`, `update_only`, and `limit`—and use them to render the appropriate form controls.
 
-      # States
-      valid_input: "border-green-500 focus:ring-green-500 focus:border-green-500",
-      invalid_input: "border-red-500 focus:ring-red-500 focus:border-red-500",
+You can declare a nested input with a simple block or by referencing another definition class.
 
-      # Labels and hints
-      label: "block text-sm font-medium text-gray-700 dark:text-gray-200 mb-1",
-      hint: "mt-2 text-sm text-gray-500 dark:text-gray-200",
-      error: "mt-2 text-sm text-red-600 dark:text-red-500"
-    })
-  end
+::: code-group
+```ruby [Block Definition]
+# app/models/post.rb
+class Post < ApplicationRecord
+  has_many :comments
+  accepts_nested_attributes_for :comments, allow_destroy: true, limit: 5
 end
-```
-
-## Usage Patterns
-
-### Basic Form
 
-```ruby
-# Simple form
-class ContactForm < Plutonium::UI::Form::Base
-  def form_template
-    render field(:name).input_tag(as: :string)
-    render field(:email).input_tag(as: :email)
-    render field(:message).textarea_tag
-    render field(:phone).int_tel_input_tag
+# app/definitions/post_definition.rb
+class PostDefinition < Plutonium::Resource::Definition
+  # This automatically inherits allow_destroy: true and limit: 5 from the model
+  nested_input :comments do |n|
+    n.input :content, as: :textarea
+    n.input :author_name, as: :string
   end
 end
 ```
 
-### Field Rendering and Wrappers
-
-All fields must be explicitly rendered using the `render` method. Use wrappers to control layout and styling:
-
-```ruby
-class PostForm < Plutonium::UI::Form::Resource
-  def form_template
-    # Basic field rendering
-    render field(:title).input_tag
-
-    # Field with wrapper styling
-    render field(:content).wrapped(class: "col-span-full") do |f|
-      render f.easymde_tag
-    end
+```ruby [Reference Definition]
+# app/models/post.rb
+class Post < ApplicationRecord
+  has_many :tags
+  accepts_nested_attributes_for :tags, update_only: true
+end
 
-    # Custom wrapper with data attributes
-    render field(:author).wrapped(
-      class: "border rounded-lg p-4",
-      data: { controller: "tooltip" }
-    ) do |f|
-      render f.belongs_to_tag
-    end
-  end
+# app/definitions/post_definition.rb
+class PostDefinition < Plutonium::Resource::Definition
+  # This inherits update_only: true from the model
+  nested_input :tags,
+               using: TagDefinition,
+               fields: %i[name color]
 end
 ```
+:::
 
-### Resource Form
+### Overriding Configuration
 
-```ruby
-# Automatic resource form based on definition
-class PostsController < ApplicationController
-  def new
-    @post = Post.new
-    @form = Plutonium::UI::Form::Resource.new(
-      @post,
-      resource_definition: current_definition
-    )
-  end
+While Plutonium automatically uses your Rails configuration, you can easily override it by passing options directly to the `nested_input` method. Explicit options always take precedence.
 
-  def edit
-    @post = Post.find(params[:id])
-    @form = Plutonium::UI::Form::Resource.new(
-      @post,
-      resource_definition: current_definition
-    )
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  # Explicit options override the model's configuration
+  nested_input :comments,
+               allow_destroy: false,  # Overrides model's allow_destroy: true
+               limit: 10,             # Overrides model's limit: 5
+               description: "Add up to 10 comments for this post." do |n|
+    n.input :content
   end
 end
-
-# In view
-<%= render @form %>
 ```
 
-### Custom Form Components
-
-```ruby
-# Create custom input component
-class ColorPickerComponent < Plutonium::UI::Form::Components::Input
-  def view_template
-    div(data: { controller: "color-picker" }) do
-      input(**attributes, type: :color)
-      input(**color_text_attributes, type: :text, placeholder: "#000000")
-    end
-  end
+### Automatic Rendering
 
-  private
+The `Form::Resource` class automatically renders the nested form based on your definition:
+- For `has_many` associations, it provides "Add" and "Remove" buttons, respecting the `limit`.
+- For `has_one` and `belongs_to` associations, it renders inline fields for a single record.
+- If `allow_destroy: true`, a "Delete" checkbox is rendered for persisted records.
+- If `update_only: true`, the "Add" button is hidden.
 
-  def color_text_attributes
-    attributes.merge(
-      name: "#{attributes[:name]}_text",
-      data: { color_picker_target: "text" }
-    )
-  end
-end
+::: details Nested Rendering Internals
+The `render_nested_resource_field` method orchestrates the rendering of the nested form, including the header, existing records, the "add" button, and the template for new records. This is all managed by the `nested-resource-form-fields` Stimulus controller.
+:::
 
-# Register in form builder
-class CustomFormBuilder < Plutonium::UI::Form::Base::Builder
-  def color_picker_tag(**options, &block)
-    create_component(ColorPickerComponent, :color_picker, **options, &block)
-  end
-end
+## Theming
 
-# Use in form
-render field(:brand_color).color_picker_tag
-```
+Forms are styled using a comprehensive theme system that leverages Tailwind CSS utility classes. The theme is defined in `lib/plutonium/ui/form/theme.rb`.
 
-### Nested Resources
+::: details Form Theme Configuration
+The `Plutonium::UI::Form::Theme.theme` method returns a hash where keys represent form elements (like `input`, `label`, `error`) and values are the corresponding CSS classes. It includes styles for layout, inputs in different states (valid, invalid), and all custom components.
 
 ```ruby
-class PostForm < Plutonium::UI::Form::Resource
-  def form_template
-    field(:title).input_tag
-    field(:content).easymde_tag
-
-    # Nested comments
-    nested(:comments, allow_destroy: true) do |comment_form|
-      comment_form.field(:content).textarea_tag
-      comment_form.field(:author_name).input_tag(as: :string)
-    end
-  end
-end
-```
-
-## JavaScript Integration
-
-### Automatic Dependencies
-
-Plutonium automatically includes JavaScript libraries for enhanced form components:
-- **EasyMDE** for markdown editing
-- **Flatpickr** for date/time picking
-- **Intl-Tel-Input** for phone inputs
-- **Uppy** for file uploads
-
-### Stimulus Controllers
-
-Each enhanced component uses a Stimulus controller for initialization and cleanup:
-
-```javascript
-// easymde_controller.js
-export default class extends Controller {
-  connect() {
-    this.editor = new EasyMDE({
-      element: this.element,
-      spellChecker: false,
-      toolbar: ["bold", "italic", "heading", "|", "quote"]
-    });
-  }
-
-  disconnect() {
-    if (this.editor) {
-      this.editor.toTextArea();
-      this.editor = null;
-    }
-  }
-}
-
-// flatpickr_controller.js
-export default class extends Controller {
-  connect() {
-    this.picker = new flatpickr(this.element, this.#buildOptions());
-  }
-
-  disconnect() {
-    if (this.picker) {
-      this.picker.destroy();
-      this.picker = null;
-    }
-  }
-
-  #buildOptions() {
-    let options = { altInput: true };
-    if (this.element.attributes.type.value == "datetime-local") {
-      options.enableTime = true;
-    } else if (this.element.attributes.type.value == "time") {
-      options.enableTime = true;
-      options.noCalendar = true;
-    }
-    return options;
-  }
-}
-```
-
-## Advanced Features
+class Plutonium::UI::Form::Theme < Phlexi::Form::Theme
+  def self.theme
+    super.merge({
+      # Layout
+      base: "relative bg-white dark:bg-gray-800 shadow-md sm:rounded-lg my-3 p-6 space-y-6",
+      fields_wrapper: "grid grid-cols-1 md:grid-cols-2 2xl:grid-cols-4 gap-4",
+      actions_wrapper: "flex justify-end space-x-2",
 
-### Form Validation
+      # Input styling
+      input: "w-full p-2 border rounded-md shadow-sm dark:bg-gray-700 focus:ring-2",
+      valid_input: "bg-green-50 border-green-500 ...",
+      invalid_input: "bg-red-50 border-red-500 ...",
 
-```ruby
-class PostForm < Plutonium::UI::Form::Resource
-  def form_template
-    # Client-side validation attributes
-    render field(:title).input_tag(
-      required: true,
-      minlength: 3,
-      maxlength: 100
-    )
-
-    render field(:email).input_tag(
-      type: :email,
-      pattern: "[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$"
-    )
-
-    # Custom validation with JavaScript
-    render field(:password).input_tag(
-      type: :password,
-      data: {
-        controller: "password-validator",
-        action: "input->password-validator#validate"
-      }
-    )
+      # Enhanced component themes (aliases to base styles)
+      flatpickr: :input,
+      int_tel_input: :input,
+      uppy: :file,
+      association: :select,
+      # ...
+    })
   end
 end
 ```
+:::
 
-### Dynamic Forms
+## JavaScript & Stimulus
 
-The recommended way to create dynamic forms is by using the `condition` and `pre_submit` options in your resource definition file. This keeps the logic declarative and out of custom form classes.
+Interactivity is powered by a set of dedicated Stimulus controllers. Plutonium automatically loads these controllers and the required third-party libraries.
 
-```ruby
-# app/definitions/post_definition.rb
-class PostDefinition < Plutonium::Resource::Definition
-  # This input will trigger a form refresh whenever its value changes.
-  input :send_notifications, as: :boolean, pre_submit: true
-
-  # This input will only be shown if the `condition` evaluates to true.
-  # The condition is re-evaluated after a pre-submit refresh.
-  input :notification_channel,
-        as: :select,
-        collection: %w[Email SMS Push],
-        condition: -> { object.send_notifications? }
-end
-```
-::: tip
-For more details on how to configure conditional inputs, see the [Definition Module documentation](./definition.md#4-add-conditional-logic).
-:::
+- **`form`**: The main controller for handling pre-submit refreshes (for conditional fields).
+- **`nested-resource-form-fields`**: Manages adding and removing nested form fields dynamically.
+- **`slim-select`**: Initializes the SlimSelect library on select fields.
+- **`easymde`**, **`flatpickr`**, **`intl-tel-input`**: Controllers for their respective input components.
+- **`attachment-input`** & **`attachment-preview`**: Work together to manage the Uppy file upload experience.