plutonium 0.50.0 → 0.51.0

data/docs/reference/definition/fields.md

@@ -1,383 +0,0 @@
-# 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: :markdown
-
-  # 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** | `:markdown` (uses EasyMDE editor) |
-| **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
-```
-
-## Value Formatting
-
-Use `formatter` for simple value transformations without a full block:
-
-```ruby
-# Truncate long text
-column :description, formatter: ->(value) { value&.truncate(30) }
-
-# Format numbers
-column :price, formatter: ->(value) { "$%.2f" % value if value }
-
-# Transform values
-column :status, formatter: ->(value) { value&.humanize&.upcase }
-```
-
-The `formatter` option:
-- Receives the field value as its argument
-- Returns the transformed value for display
-- Works with `column` and `display` declarations
-- Is simpler than block syntax when you only need to transform the value
-
-**formatter vs block:** Use `formatter` when you only need the value. Use a block when you need access to the full record:
-
-```ruby
-# formatter - receives just the value
-column :name, formatter: ->(value) { value&.titleize }
-
-# block - receives the full record
-column :full_name do |record|
-  "#{record.first_name} #{record.last_name}"
-end
-```
-
-## 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: :markdown     # Form: EasyMDE 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

@@ -1,326 +0,0 @@
-# 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: :markdown
-
-  # 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: :markdown
-
-  # 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
-```
-
-## Form Configuration
-
-Control form behavior:
-
-```ruby
-class PostDefinition < Plutonium::Resource::Definition
-  # Controls "Save and add another" / "Update and continue editing" buttons
-  # nil (default) = auto-detect (hidden for singular resources, shown for plural)
-  # true = always show
-  # false = always hide
-  submit_and_continue false
-
-  # How `:new` / `:edit` render. Default is :slideover.
-  #   :slideover — slide-in panel from the right (default)
-  #   :centered  — centered modal dialog
-  #   false      — full standalone pages (no modal)
-  modal :centered
-end
-```
-
-Singular resources (e.g., `resource :profile` routes or `has_one` nested) auto-hide the secondary submit button since creating "another" doesn't make sense.
-
-The `modal` setting only retargets the framework-provided `:new` / `:edit` actions. Custom interactive actions render in their own dialog whose chrome is set on the action via the per-action `modal:` option (`:centered` default, or `:slideover`) — see [Actions](./actions#action-options).
-
-## Show Page Metadata Panel
-
-The `metadata` DSL declares a list of fields that render in a right-side aside on the show page as label/value rows, leaving the main card focused on the record's substance.
-
-```ruby
-class PostDefinition < Plutonium::Resource::Definition
-  metadata :author, :state, :created_at, :updated_at
-end
-```
-
-- **Opt-in.** Without a `metadata` call, the show page renders full-width with no aside.
-- **Policy-aware.** Fields are intersected with the policy's permitted attributes. The panel auto-hides when nothing is permitted.
-- **Deduplicated.** Fields listed in `metadata` are removed from the main card so values aren't shown twice.
-- **Responsive.** Side-by-side at `lg+`, stacked single-column below.
-
-Field formatting (label, `as:`, blocks) is shared with the main card — declare once via `field` / `display` and the metadata panel inherits it.
-
-## Index Views (Table & Grid)
-
-Resources can opt into a card-based **Grid** view alongside the default **Table** view. The user can switch between them via the toolbar; the choice is persisted per-resource via cookie.
-
-```ruby
-class UserDefinition < Plutonium::Resource::Definition
-  views :table, :grid       # enable both
-  default_view :grid        # initial view if no cookie
-
-  grid_fields(
-    image:     :avatar,     # ActiveStorage attachment, Shrine, or URL string
-    header:    :name,       # falls back to record.to_label
-    subheader: :email,
-    body:      :bio,
-    meta:      [:role, :status],   # rendered as small pills
-    footer:    :last_seen_at       # falls back to :created_at
-  )
-
-  grid_layout :media        # :compact (default) or :media
-  grid_columns 3            # pin to 3 cols on lg+; default is 1/2/3/4 responsive
-end
-```
-
-| Method | Purpose |
-|--------|---------|
-| `views :table, :grid` | Which views are available. Default `[:table]`. |
-| `default_view :grid` | Initial view when no cookie. Falls back to first declared view. |
-| `grid_fields(...)` | Maps card slots to fields. **Implicitly enables `:grid`** if not already declared. |
-| `grid_layout :media` | `:compact` (image left of content) or `:media` (full-width image on top). |
-| `grid_columns 3` | Override responsive column count on `lg+`. Default is 1 / 2 / 3 / 4 at sm/md/lg/xl. |
-
-Grid slots — `:image`, `:header`, `:subheader`, `:body`, `:meta`, `:footer` — are all optional. `:meta` accepts an array; the rest are single fields. Slots that point at fields not permitted by the user's policy collapse silently.
-
-## 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/)