plutonium 0.33.1 → 0.34.0

data/docs/reference/definition/fields.md

@@ -0,0 +1,350 @@
+# Definition Fields
+
+Complete reference for field configuration in definitions.
+
+## Core Methods
+
+| Method | Applies To | Use When |
+|--------|-----------|----------|
+| `field` | Forms + Show + Table | Universal type override |
+| `input` | Forms only | Form-specific options |
+| `display` | Show page only | Display-specific options |
+| `column` | Table only | Table-specific options |
+
+## Basic Usage
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  # field - changes type everywhere
+  field :content, as: :rich_text
+
+  # input - form-specific
+  input :title,
+    label: "Article Title",
+    hint: "Enter a descriptive title",
+    placeholder: "e.g. Getting Started"
+
+  # display - show page specific
+  display :content,
+    as: :markdown,
+    description: "Published content",
+    wrapper: {class: "col-span-full"}
+
+  # column - table specific
+  column :title, label: "Article", align: :center
+  column :view_count, align: :end
+end
+```
+
+## Available Field Types
+
+### Input Types (Forms)
+
+| Category | Types |
+|----------|-------|
+| **Text** | `:string`, `:text`, `:email`, `:url`, `:tel`, `:password` |
+| **Rich Text** | `:rich_text`, `:markdown` |
+| **Numeric** | `:number`, `:integer`, `:decimal`, `:range` |
+| **Boolean** | `:boolean` |
+| **Date/Time** | `:date`, `:time`, `:datetime` |
+| **Selection** | `:select`, `:slim_select`, `:radio_buttons`, `:check_boxes` |
+| **Files** | `:file`, `:uppy`, `:attachment` |
+| **Associations** | `:association`, `:secure_association`, `:belongs_to`, `:has_many`, `:has_one` |
+| **Special** | `:hidden`, `:color`, `:phone` |
+
+### Display Types (Show/Index)
+
+`:string`, `:text`, `:email`, `:url`, `:phone`, `:markdown`, `:number`, `:integer`, `:decimal`, `:boolean`, `:date`, `:time`, `:datetime`, `:association`, `:attachment`
+
+## Field Options
+
+### Common Options
+
+```ruby
+input :title,
+  label: "Custom Label",           # Custom label text
+  hint: "Help text for forms",     # Form help text
+  placeholder: "Enter value",      # Input placeholder
+  description: "For displays"      # Display description
+```
+
+### HTML Attributes
+
+```ruby
+input :title,
+  class: "custom-class",           # CSS class
+  data: {controller: "custom"},    # Data attributes
+  required: true,                  # HTML required
+  readonly: true,                  # HTML readonly
+  disabled: true                   # HTML disabled
+```
+
+### Wrapper Options
+
+```ruby
+display :content, wrapper: {class: "col-span-full"}
+input :notes, wrapper: {class: "bg-gray-50"}
+```
+
+## Select/Choices
+
+### Static Choices
+
+```ruby
+input :category, as: :select, choices: %w[Tech Business Lifestyle]
+input :status, as: :select, choices: Post.statuses.keys
+```
+
+### Dynamic Choices (requires block)
+
+```ruby
+# Basic dynamic
+input :author do |f|
+  choices = User.active.pluck(:name, :id)
+  f.select_tag choices: choices
+end
+
+# With context access
+input :team_members do |f|
+  choices = current_user.organization.users.pluck(:name, :id)
+  f.select_tag choices: choices
+end
+
+# Based on object state
+input :related_posts do |f|
+  choices = if object.persisted?
+    Post.where.not(id: object.id).published.pluck(:title, :id)
+  else
+    []
+  end
+  f.select_tag choices: choices
+end
+```
+
+## Conditional Rendering
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  # Show based on object state
+  display :published_at, condition: -> { object.published? }
+  display :rejection_reason, condition: -> { object.rejected? }
+
+  # Show based on environment
+  field :debug_info, condition: -> { Rails.env.development? }
+end
+```
+
+**Note:** Use `condition` for UI state logic. Use **policies** for authorization.
+
+## Dynamic Forms (pre_submit)
+
+Use `pre_submit: true` to create forms that dynamically show/hide fields based on other field values.
+
+### Basic Pattern
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  # Trigger field - causes form to re-render on change
+  input :send_notifications, pre_submit: true
+
+  # Dependent field - only shown when condition is true
+  input :notification_channel,
+    as: :select,
+    choices: %w[Email SMS],
+    condition: -> { object.send_notifications? }
+end
+```
+
+### How It Works
+
+1. User changes a `pre_submit: true` field
+2. Form submits via Turbo (no page reload)
+3. Server re-renders the form with updated `object` state
+4. Fields with `condition` procs are re-evaluated
+5. Newly visible fields appear, hidden fields disappear
+
+## Custom Rendering
+
+### Block Syntax
+
+**For Display (can return any component):**
+
+```ruby
+display :status do |field|
+  StatusBadgeComponent.new(value: field.value, class: field.dom.css_class)
+end
+
+display :metrics do |field|
+  if field.value.present?
+    MetricsChartComponent.new(data: field.value)
+  else
+    EmptyStateComponent.new(message: "No metrics")
+  end
+end
+```
+
+**For Input (must use form builder methods):**
+
+```ruby
+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
+```
+
+### phlexi_tag (Advanced Display)
+
+```ruby
+# With component class
+display :status, as: :phlexi_tag, with: StatusBadgeComponent
+
+# With inline proc
+display :priority, as: :phlexi_tag, with: ->(value, attrs) {
+  case value
+  when 'high'
+    span(class: "badge badge-danger") { "High" }
+  when 'medium'
+    span(class: "badge badge-warning") { "Medium" }
+  else
+    span(class: "badge badge-info") { "Low" }
+  end
+}
+```
+
+### Custom Component Class
+
+```ruby
+input :color_picker, as: ColorPickerComponent
+display :chart, as: ChartComponent
+```
+
+## Column Alignment
+
+```ruby
+column :title, align: :start    # Left (default)
+column :status, align: :center  # Center
+column :amount, align: :end     # Right
+```
+
+## Nested Inputs
+
+Render inline forms for associated records. Requires `accepts_nested_attributes_for` on the model.
+
+### Model Setup
+
+```ruby
+class Post < ResourceRecord
+  has_many :comments
+  has_one :metadata
+
+  accepts_nested_attributes_for :comments, allow_destroy: true, limit: 10
+  accepts_nested_attributes_for :metadata, update_only: true
+end
+```
+
+### Basic Declaration
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  # Block syntax
+  nested_input :comments do |n|
+    n.input :body, as: :text
+    n.input :author_name
+  end
+
+  # Using another definition
+  nested_input :metadata, using: PostMetadataDefinition, fields: %i[seo_title seo_description]
+end
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `limit` | Max records (auto-detected from model, default: 10) |
+| `allow_destroy` | Show delete checkbox (auto-detected from model) |
+| `update_only` | Hide "Add" button, only edit existing |
+| `description` | Help text above the section |
+| `condition` | Proc to show/hide section |
+| `using` | Reference another Definition class |
+| `fields` | Which fields to render from the definition |
+
+```ruby
+nested_input :amenities,
+  allow_destroy: true,
+  limit: 20,
+  description: "Add property amenities" do |n|
+    n.input :name
+    n.input :icon, as: :select, choices: ICONS
+  end
+```
+
+## File Uploads
+
+```ruby
+input :avatar, as: :file
+input :avatar, as: :uppy
+
+input :documents, as: :file, multiple: true
+input :documents, as: :uppy,
+  allowed_file_types: ['.pdf', '.doc'],
+  max_file_size: 5.megabytes
+```
+
+## Common Patterns
+
+### Rich Text Content
+
+```ruby
+field :content, as: :rich_text    # Form: rich editor
+display :content, as: :markdown   # Show: rendered markdown
+```
+
+### Money Fields
+
+```ruby
+input :price, as: :decimal, class: "font-mono"
+display :price, class: "font-bold text-green-600"
+```
+
+### Status Badges
+
+```ruby
+display :status do |field|
+  color = case field.value
+  when 'active' then 'green'
+  when 'pending' then 'yellow'
+  else 'gray'
+  end
+  span(class: "badge badge-#{color}") { field.value.humanize }
+end
+```
+
+### Hidden Fields
+
+```ruby
+field :author_id, as: :hidden
+input :tenant_id, as: :hidden
+```
+
+## Context in Blocks
+
+Inside `condition` procs and `input` blocks:
+- `object` - The record being edited/displayed
+- `current_user` - The authenticated user
+- `current_parent` - Parent record for nested resources
+- `request`, `params` - Request information
+- All helper methods
+
+## Related
+
+- [Definition Reference](./index)
+- [Actions Reference](./actions)
+- [Query Reference](./query)
+- [Forms Reference](/reference/views/forms)

data/docs/reference/definition/index.md

@@ -0,0 +1,252 @@
+# Definition Reference
+
+Complete reference for resource definitions.
+
+## Overview
+
+Definitions control how resources render - which fields appear in forms, how tables display data, what actions are available.
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  # Field configuration
+  field :title
+  field :body, as: :rich_text
+
+  # Form-specific
+  input :title, placeholder: "Enter title"
+
+  # Display-specific
+  display :body, as: :markdown
+
+  # Table columns
+  column :title
+
+  # Custom actions
+  action :publish, interaction: PublishPost
+
+  # Search
+  search do |scope, query|
+    scope.where("title ILIKE ?", "%#{query}%")
+  end
+
+  # Sorting
+  sort :title
+  sort :created_at
+  default_sort :created_at, :desc
+end
+```
+
+## Definition Files
+
+### Location
+
+```
+app/definitions/post_definition.rb
+packages/blogging/app/definitions/blogging/post_definition.rb
+```
+
+### Naming Convention
+
+| Model | Definition |
+|-------|------------|
+| `Post` | `PostDefinition` |
+| `Blogging::Post` | `Blogging::PostDefinition` |
+
+### Portal-Specific
+
+Override for specific portals:
+
+```ruby
+# packages/admin_portal/app/definitions/admin_portal/post_definition.rb
+module AdminPortal
+  class PostDefinition < ::PostDefinition
+    # Admin-specific customizations
+    field :internal_notes
+  end
+end
+```
+
+## Auto-Detection
+
+By default, Plutonium auto-detects fields from the model:
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  # Empty definition = all fields auto-detected
+end
+```
+
+Override selectively:
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  # Override just body field
+  field :body, as: :rich_text
+
+  # Other fields still auto-detected
+end
+```
+
+## Core Methods
+
+### Field Declaration
+
+| Method | Purpose |
+|--------|---------|
+| `field` | Universal type/options for forms, displays, tables |
+| `input` | Form-specific configuration |
+| `display` | Show page configuration |
+| `column` | Table configuration |
+
+### Query Configuration
+
+| Method | Purpose |
+|--------|---------|
+| `search` | Full-text search block |
+| `filter` | Sidebar filter inputs |
+| `scope` | Quick filter buttons |
+| `sort` / `sorts` | Sortable columns |
+| `default_sort` | Default sort order |
+
+### Actions
+
+| Method | Purpose |
+|--------|---------|
+| `action` | Define custom actions |
+| `nested_input` | Nested forms for associations |
+
+## Page Configuration
+
+Configure page titles and descriptions:
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  index_page_title "All Posts"
+  index_page_description "Manage your blog posts"
+
+  new_page_title "Create Post"
+  new_page_description "Add a new blog post"
+
+  show_page_title { |record| record.title }
+  show_page_description "View post details"
+
+  edit_page_title { |record| "Edit: #{record.title}" }
+  edit_page_description "Update post content"
+end
+```
+
+## Breadcrumbs
+
+Control breadcrumb display:
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  # Disable breadcrumbs globally
+  breadcrumbs false
+
+  # Or per-page
+  index_page_breadcrumbs true
+  new_page_breadcrumbs true
+  show_page_breadcrumbs true
+  edit_page_breadcrumbs true
+  interactive_action_page_breadcrumbs true
+end
+```
+
+## Custom Page Classes
+
+Override default page components:
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  # Custom page classes
+  class IndexPage < Plutonium::UI::Page::Index
+    def render_header
+      # Custom header
+    end
+  end
+
+  class Form < Plutonium::UI::Form::Resource
+    # Custom form behavior
+  end
+
+  class Table < Plutonium::UI::Table::Resource
+    # Custom table behavior
+  end
+
+  class Display < Plutonium::UI::Display::Resource
+    # Custom display behavior
+  end
+end
+```
+
+## Inheritance
+
+Definitions inherit from each other:
+
+```ruby
+# Base definition
+class PostDefinition < Plutonium::Resource::Definition
+  field :title
+  field :body
+end
+
+# Extended definition
+class AdminPortal::PostDefinition < ::PostDefinition
+  field :internal_notes
+  field :moderation_status
+end
+```
+
+## Customization Hooks
+
+Override customization methods for dynamic configuration:
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  def customize_fields
+    field :dynamic_field if some_condition?
+  end
+
+  def customize_inputs
+    input :special_input, as: :text
+  end
+
+  def customize_displays
+    display :computed_value
+  end
+
+  def customize_columns
+    column :extra_column
+  end
+
+  def customize_filters
+    filter :status, with: Plutonium::Query::Filters::Text, predicate: :eq
+  end
+
+  def customize_scopes
+    scope :active
+  end
+
+  def customize_sorts
+    sort :custom_field
+  end
+
+  def customize_actions
+    action :dynamic_action, interaction: SomeInteraction
+  end
+end
+```
+
+## Sections
+
+- [Fields](./fields) - Form and display field configuration
+- [Actions](./actions) - Custom actions and buttons
+- [Query](./query) - Search, filters, scopes, and sorting
+
+## Related
+
+- [Fields](./fields) - Field configuration
+- [Actions](./actions) - Custom actions
+- [Query](./query) - Search, filters, scopes
+- [Views Reference](/reference/views/)