plutonium 0.50.0 → 0.51.0

data/docs/reference/views/forms.md

@@ -1,411 +0,0 @@
-# Forms Reference
-
-Complete reference for form customization using Phlexi::Form.
-
-## Overview
-
-Plutonium forms are built on [Phlexi::Form](https://github.com/radioactive-labs/phlexi-form), providing a Ruby-first approach to form building.
-
-## Form Class Hierarchy
-
-```
-Phlexi::Form::Base
-└── Plutonium::UI::Form::Base       # Base with Plutonium components
-    ├── Plutonium::UI::Form::Resource   # Resource CRUD forms
-    │   └── Plutonium::UI::Form::Interaction  # Interactive action forms
-    └── Plutonium::UI::Form::Query      # Search/filter forms
-```
-
-## Custom Form Template
-
-Override form rendering in your definition:
-
-```ruby
-class PostDefinition < ResourceDefinition
-  class Form < Form
-    def form_template
-      # Your custom layout
-      render_fields
-      render_actions
-    end
-  end
-end
-```
-
-### Form Template Methods
-
-| Method | Description |
-|--------|-------------|
-| `form_template` | Main template method to override |
-| `render_fields` | Render all permitted fields |
-| `render_resource_field(name)` | Render a single field by name |
-| `render_actions` | Render submit buttons |
-| `fields_wrapper { }` | Wrapper div for field grid |
-| `actions_wrapper { }` | Wrapper div for buttons |
-
-### Form Attributes
-
-| Attribute | Description |
-|-----------|-------------|
-| `object` / `record` | The form object being edited |
-| `resource_fields` | Array of permitted field names |
-| `resource_definition` | The definition instance |
-
-## Custom Layouts
-
-### Sectioned Form
-
-```ruby
-class PostDefinition < ResourceDefinition
-  class Form < Form
-    def form_template
-      section("Basic Information") {
-        render_resource_field :title
-        render_resource_field :slug
-      }
-
-      section("Content") {
-        render_resource_field :content
-        render_resource_field :excerpt
-      }
-
-      render_actions
-    end
-
-    private
-
-    def section(title, &)
-      div(class: "mb-8") {
-        h3(class: "text-lg font-semibold mb-4") { title }
-        fields_wrapper(&)
-      }
-    end
-  end
-end
-```
-
-### Two-Column Layout
-
-```ruby
-class Form < Form
-  def form_template
-    div(class: "grid grid-cols-1 lg:grid-cols-3 gap-6") {
-      # Main content - 2 columns
-      div(class: "lg:col-span-2") {
-        fields_wrapper {
-          render_resource_field :title
-          render_resource_field :content
-        }
-      }
-
-      # Sidebar - 1 column
-      div(class: "space-y-4") {
-        Panel {
-          h4(class: "font-medium mb-2") { "Settings" }
-          render_resource_field :status
-          render_resource_field :visibility
-        }
-      }
-    }
-
-    render_actions
-  end
-end
-```
-
-## Field Builder
-
-When using `render_resource_field`, Plutonium applies definition configuration. For custom rendering, use the `field` method directly.
-
-### Basic Field Usage
-
-```ruby
-def form_template
-  # Using field builder directly
-  render field(:title).wrapped { |f| f.input_tag }
-  render field(:content).wrapped { |f| f.easymde_tag }
-  render field(:published).wrapped { |f| f.checkbox_tag }
-
-  render_actions
-end
-```
-
-### Standard Tag Methods
-
-| Method | Input Type |
-|--------|------------|
-| `f.input_tag` | Text input (auto-detects type) |
-| `f.string_tag` | Text input |
-| `f.text_tag` | Textarea |
-| `f.number_tag` | Number input |
-| `f.email_tag` | Email input |
-| `f.password_tag` | Password input |
-| `f.url_tag` | URL input |
-| `f.phone_tag` | Telephone input |
-| `f.hidden_tag` | Hidden input |
-| `f.date_tag` | Date input |
-| `f.time_tag` | Time input |
-| `f.datetime_tag` | Datetime input |
-| `f.checkbox_tag` | Checkbox |
-| `f.boolean_tag` | Checkbox (themed as boolean) |
-| `f.select_tag` | Select dropdown |
-| `f.radio_button_tag` | Radio button |
-| `f.collection_radio_buttons_tag` | Radio button collection |
-| `f.collection_checkboxes_tag` | Checkbox collection |
-| `f.range_tag` | Range slider |
-| `f.file_input_tag` | File input |
-
-### Plutonium-Enhanced Tags
-
-Plutonium extends the form builder with additional tags. See the [Form::Base::Builder source](https://github.com/radioactive-labs/plutonium-core/blob/master/lib/plutonium/ui/form/base.rb) for the current list.
-
-Common ones include:
-- `f.easymde_tag` / `f.markdown_tag` - Markdown editor
-- `f.slim_select_tag` - Enhanced select
-- `f.flatpickr_tag` - Date/time picker
-- `f.uppy_tag` / `f.file_tag` - File upload
-- `f.secure_association_tag` - Association with SGID
-
-### Field with Options
-
-```ruby
-# Select with choices
-render field(:status).wrapped { |f|
-  f.select_tag(choices: %w[draft published archived])
-}
-
-# Date picker with options
-render field(:published_at).wrapped { |f|
-  f.flatpickr_tag(min_date: Date.today, enable_time: true)
-}
-
-# File upload with restrictions
-render field(:avatar).wrapped { |f|
-  f.uppy_tag(
-    allowed_file_types: %w[.jpg .png .gif],
-    max_file_size: 5.megabytes
-  )
-}
-```
-
-### Wrapped vs Unwrapped
-
-```ruby
-# Wrapped - includes label, hint, errors
-render field(:title).wrapped { |f| f.input_tag }
-
-# Unwrapped - just the input element
-render field(:title).input_tag
-
-# Custom wrapper options
-render field(:title).wrapped(class: "col-span-full") { |f|
-  f.input_tag
-}
-```
-
-## Input Configuration in Definitions
-
-Define inputs in the definition, render them in the form:
-
-```ruby
-class PostDefinition < ResourceDefinition
-  # Configure inputs
-  input :title, hint: "Be descriptive", placeholder: "Enter title"
-  input :content, as: :markdown
-  input :status, as: :select, choices: %w[draft published]
-  input :published_at, as: :flatpickr
-
-  # Custom input with block
-  input :category do |f|
-    choices = Category.active.pluck(:name, :id)
-    f.select_tag(choices: choices)
-  end
-
-  class Form < Form
-    def form_template
-      # render_resource_field uses the input configuration
-      render_resource_field :title
-      render_resource_field :content
-      render_resource_field :status
-      render_resource_field :published_at
-      render_resource_field :category
-
-      render_actions
-    end
-  end
-end
-```
-
-## Nested Forms
-
-For `has_many` / `has_one` associations with `accepts_nested_attributes_for`:
-
-### Model Setup
-
-```ruby
-class Post < ResourceRecord
-  has_many :comments
-  accepts_nested_attributes_for :comments, allow_destroy: true
-end
-```
-
-### Definition Setup
-
-```ruby
-class PostDefinition < ResourceDefinition
-  nested_input :comments do |n|
-    n.input :author_name
-    n.input :body, as: :text
-  end
-
-  # Or reference another definition
-  nested_input :comments, using: CommentDefinition, fields: %i[author_name body]
-end
-```
-
-### Rendering
-
-```ruby
-class Form < Form
-  def form_template
-    render_resource_field :title
-    render_resource_field :content
-
-    # Nested fields are automatically handled
-    render_resource_field :comments
-
-    render_actions
-  end
-end
-```
-
-## Dynamic Forms (pre_submit)
-
-Fields with `pre_submit: true` trigger form re-rendering on change:
-
-```ruby
-class PostDefinition < ResourceDefinition
-  input :post_type, as: :select,
-    choices: %w[article video podcast],
-    pre_submit: true
-
-  input :video_url,
-    condition: -> { object.post_type == "video" }
-
-  input :podcast_url,
-    condition: -> { object.post_type == "podcast" }
-end
-```
-
-When `post_type` changes, the form re-renders via Turbo and shows/hides conditional fields.
-
-## Form Actions
-
-### Submit and Continue Button
-
-Forms include a secondary button ("Create and add another" for new records, "Update and continue editing" for existing). Control this in your definition:
-
-```ruby
-class PostDefinition < ResourceDefinition
-  # nil (default) = auto-detect (hidden for singular resources, shown for plural)
-  # true = always show
-  # false = always hide
-  submit_and_continue false
-end
-```
-
-Singular resources (e.g., `resource :profile` routes or `has_one` nested) auto-hide this button.
-
-### Default Actions
-
-```ruby
-def render_actions
-  actions_wrapper {
-    render submit_button
-  }
-end
-```
-
-### Custom Actions
-
-```ruby
-def render_actions
-  actions_wrapper {
-    # Cancel link
-    a(href: resource_url_for(resource_class), class: "btn btn-secondary") {
-      "Cancel"
-    }
-
-    # Save as draft
-    button(type: :submit, name: "draft", value: "1", class: "btn") {
-      "Save Draft"
-    }
-
-    # Primary submit
-    render submit_button
-  }
-end
-```
-
-## Form Context
-
-Inside form templates:
-
-```ruby
-class Form < Form
-  def form_template
-    # Form object
-    object              # The record
-    record              # Alias for object
-    object.new_record?  # Check if creating
-
-    # Request context
-    current_user
-    current_parent
-    request
-    params
-
-    # Definition
-    resource_definition
-    resource_fields     # Permitted fields
-
-    # URL helpers
-    resource_url_for(object)
-    resource_url_for(Post, action: :new)
-
-    # Rails helpers
-    helpers.link_to(...)
-  end
-end
-```
-
-## Interaction Forms
-
-Forms for interactive actions:
-
-```ruby
-class PublishPostInteraction < ResourceInteraction
-  attribute :publish_date, :date
-  attribute :notify_subscribers, :boolean, default: true
-
-  input :publish_date, as: :flatpickr
-  input :notify_subscribers
-
-  # Custom form (optional)
-  class Form < Plutonium::UI::Form::Interaction
-    def form_template
-      div(class: "space-y-4") {
-        render_resource_field :publish_date
-        render_resource_field :notify_subscribers
-      }
-      render_actions
-    end
-  end
-end
-```
-
-## Related
-
-- [Fields Reference](/reference/definition/fields) - Input configuration
-- [Views Reference](./index) - Custom page classes
-- [Theming Guide](/guides/theming) - TailwindCSS and styling