elaine_crud 0.1.0

data/docs/DSL_EXAMPLES.md

@@ -0,0 +1,313 @@
+# ElaineCrud DSL Examples
+
+This document shows comprehensive examples of the ElaineCrud field DSL framework that has been implemented. All examples include TODO comments since the actual functionality is not yet implemented.
+
+## Basic Field Configuration
+
+```ruby
+class PeopleController < ElaineCrud::BaseController
+  model Person
+  permit_params :name, :email, :role, :active, :company_id, :salary
+  
+  # Simple hash-style configuration
+  field :name, title: "Full Name", description: "Enter first and last name"
+  
+  # Block-style configuration for complex setups
+  field :email do |f|
+    f.title "Email Address"
+    f.description "Primary contact email"
+    f.display_as { |value| mail_to(value) if value.present? }
+    f.edit_as { |value| email_field_tag(field_name, value, class: "form-input") }
+  end
+end
+```
+
+## Dropdown Options
+
+```ruby
+class ProductController < ElaineCrud::BaseController
+  model Product
+  permit_params :name, :status, :category
+  
+  # Array of options
+  field :status, 
+    title: "Product Status",
+    options: ["draft", "published", "archived"]
+  
+  # Hash mapping display => value
+  field :category,
+    title: "Product Category", 
+    options: {
+      "Consumer Electronics" => "electronics",
+      "Home & Garden" => "home_garden", 
+      "Books & Media" => "books"
+    }
+end
+```
+
+## Foreign Key Relationships
+
+```ruby
+class EmployeeController < ElaineCrud::BaseController
+  model Employee
+  permit_params :name, :email, :company_id, :department_id
+  
+  # Basic foreign key - displays with to_s
+  field :company_id do |f|
+    f.title "Company"
+    f.description "Select the company this employee works for"
+    f.foreign_key model: Company
+  end
+  
+  # Foreign key with custom display and scoping
+  field :department_id do |f|
+    f.title "Department"
+    f.foreign_key model: Department,
+                  display: ->(dept) { "#{dept.name} (#{dept.location})" },
+                  scope: -> { Department.active.order(:name) },
+                  null_option: "Select a department..."
+  end
+end
+```
+
+## Custom Display and Edit Callbacks
+
+```ruby
+class TransactionController < ElaineCrud::BaseController
+  model Transaction
+  permit_params :amount, :description, :transaction_type, :processed_at
+  
+  # Method reference for display callback
+  field :amount,
+    title: "Transaction Amount",
+    display_as: :format_currency,
+    edit_as: :currency_input
+  
+  # Inline block for display
+  field :transaction_type do |f|
+    f.title "Type"
+    f.display_as { |value| 
+      case value
+      when 'credit' then content_tag(:span, 'Credit', class: 'text-green-600 font-semibold')
+      when 'debit' then content_tag(:span, 'Debit', class: 'text-red-600 font-semibold')
+      else value.to_s.titleize
+      end
+    }
+    f.options ["credit", "debit", "transfer"]
+  end
+  
+  private
+  
+  def format_currency(value, record)
+    number_to_currency(value) if value
+  end
+  
+  def currency_input(value, record, form)
+    form.number_field(:amount, step: 0.01, class: "form-input", placeholder: "0.00")
+  end
+end
+```
+
+## Custom Partial Rendering
+
+```ruby
+class AudienceController < ElaineCrud::BaseController
+  model Audience
+  permit_params :name, :audience_query, :state
+  
+  # Use a custom partial for complex field rendering
+  field :audience_query do |f|
+    f.title "Audience Query"
+    f.description "Build your audience targeting criteria using the visual query builder"
+    f.edit_partial "audience_query_builder"
+  end
+  
+  # Hash-style partial configuration
+  field :rich_content,
+    title: "Rich Content Editor",
+    description: "WYSIWYG editor for rich text content",
+    edit_partial: "shared/rich_text_editor"
+end
+```
+
+### Partial Template Example
+
+Then create the partial file `app/views/audience_browser/_audience_query_builder.html.erb`:
+
+## Read-Only Fields with Defaults
+
+```ruby
+class OrderController < ElaineCrud::BaseController
+  model Order
+  permit_params :customer_name, :total_amount, :status, :order_number, :created_by
+  
+  # Read-only with static default
+  field :order_number,
+    title: "Order Number",
+    description: "Automatically generated unique identifier",
+    readonly: true,
+    default_value: -> { "ORD-#{SecureRandom.alphanumeric(8).upcase}" }
+  
+  # Read-only timestamp with custom formatting
+  field :created_at,
+    title: "Order Date",
+    readonly: true,
+    display_as: :format_order_date
+  
+  # Read-only field populated from session/context
+  field :created_by,
+    title: "Created By",
+    readonly: true,
+    default_value: -> { current_user&.name }
+    
+  private
+  
+  def format_order_date(value, record)
+    value&.strftime("%B %d, %Y at %I:%M %p")
+  end
+  
+  def current_user
+    # In this app, user info comes from reverse proxy headers
+    OpenStruct.new(name: request.headers['X-Forwarded-User'])
+  end
+end
+```
+
+## Complex Real-World Example
+
+```ruby
+class UserController < ElaineCrud::BaseController
+  model User
+  permit_params :name, :email, :role, :company_id, :department_id, :salary, :active, :hire_date
+  
+  # Basic text field with validation
+  field :name do |f|
+    f.title "Full Name"
+    f.description "Enter the employee's first and last name"
+    f.display_as { |value| content_tag(:strong, value) }
+  end
+  
+  # Email with custom display and validation
+  field :email do |f|
+    f.title "Email Address"
+    f.description "Primary work email address"
+    f.display_as { |value| mail_to(value, value, class: "text-blue-600") }
+    f.edit_as { |value, record, form| 
+      form.email_field(:email, value: value, required: true, class: "form-input")
+    }
+  end
+  
+  # Dropdown with predefined options
+  field :role,
+    title: "Job Role",
+    description: "Employee's primary role in the organization",
+    options: ["Developer", "Designer", "Manager", "Admin", "HR"]
+  
+  # Foreign key to Company with custom display
+  field :company_id do |f|
+    f.title "Company"
+    f.description "Select the company this employee works for"
+    f.foreign_key model: Company,
+                  display: ->(company) { "#{company.name} (#{company.city})" },
+                  scope: -> { Company.active.includes(:address) },
+                  null_option: "Select a company..."
+  end
+  
+  # Foreign key to Department filtered by company
+  field :department_id do |f|
+    f.title "Department"
+    f.description "Select the department within the company"
+    f.foreign_key model: Department,
+                  display: :name_with_code,
+                  scope: -> { Department.joins(:company).where(company: company_scope) }
+  end
+  
+  # Currency field with formatting
+  field :salary do |f|
+    f.title "Annual Salary"
+    f.description "Base annual salary in USD"
+    f.display_as :format_salary
+    f.edit_as { |value, record, form|
+      form.number_field(:salary, value: value, step: 1000, min: 0, 
+                       class: "form-input", placeholder: "Enter amount")
+    }
+  end
+  
+  # Boolean with custom display
+  field :active,
+    title: "Active Employee",
+    description: "Is this person currently employed?",
+    display_as: ->(value) { 
+      if value
+        content_tag(:span, "✅ Active", class: "text-green-600 font-semibold")
+      else
+        content_tag(:span, "❌ Inactive", class: "text-red-600 font-semibold")
+      end
+    }
+  
+  # Date field with custom formatting
+  field :hire_date do |f|
+    f.title "Hire Date"
+    f.description "Employee's first day of work"
+    f.display_as { |value| value&.strftime("%B %d, %Y") }
+    f.default_value -> { Date.current }
+  end
+  
+  private
+  
+  def format_salary(value, record)
+    return "Not disclosed" if value.blank?
+    number_to_currency(value, precision: 0)
+  end
+  
+  def company_scope
+    # This would be used to filter departments by selected company
+    # Implementation would need to be dynamic based on form state
+    Company.all
+  end
+end
+```
+
+## Field Configuration Reference
+
+### Available Options
+
+| Option | Type | Description | Example |
+|--------|------|-------------|---------|
+| `title` | String | Human-readable field title | `"Full Name"` |
+| `description` | String | Help text for forms | `"Enter first and last name"` |
+| `readonly` | Boolean | Prevents editing | `true` |
+| `default_value` | Value/Proc | Default for new records | `-> { Date.current }` |
+| `display_as` | Symbol/Proc | Custom display rendering | `:format_currency` |
+| `edit_as` | Symbol/Proc | Custom form field rendering | `{ |v| email_field(...) }` |
+| `edit_partial` | String | Custom partial for field rendering | `"audience_query_builder"` |
+| `options` | Array/Hash | Dropdown options | `["option1", "option2"]` |
+| `foreign_key` | Hash | Foreign key configuration | `{ model: Company, display: :name }` |
+
+### Foreign Key Configuration
+
+```ruby
+field :company_id do |f|
+  f.foreign_key model: Company,                    # Required: target model
+                display: :name,                    # Optional: how to display (Symbol/Proc)
+                scope: -> { Company.active },      # Optional: filter records
+                null_option: "Select company..."   # Optional: placeholder text
+end
+```
+
+### Callback Signatures
+
+```ruby
+# Display callbacks
+display_as: :method_name          # Calls controller.method_name(value, record)
+display_as: { |value, record| ... } # Inline block
+
+# Edit callbacks  
+edit_as: :method_name             # Calls controller.method_name(value, record, form)
+edit_as: { |value, record, form| ... } # Inline block
+
+# Default value callbacks
+default_value: -> { Time.current } # Called in controller context
+```
+
+All of these examples are currently placeholders with TODO comments in the actual implementation. Each feature needs to be implemented one by one in the FieldConfiguration and BaseController classes.

data/docs/FOREIGN_KEY_EXAMPLE.rb

@@ -0,0 +1,100 @@
+# Example: Meeting Controller with Foreign Key Support
+# 
+# This example shows how ElaineCrud automatically handles foreign key relationships
+# for a Meeting model that belongs_to a MeetingRoom.
+#
+# Models (example structure):
+#
+# class Meeting < ApplicationRecord
+#   belongs_to :meeting_room
+#   
+#   validates :title, presence: true
+#   validates :start_time, presence: true
+# end
+#
+# class MeetingRoom < ApplicationRecord
+#   has_many :meetings
+#   
+#   validates :name, presence: true
+# end
+
+class MeetingsController < ElaineCrud::BaseController
+  # Set the model - this automatically detects belongs_to relationships
+  model Meeting
+  
+  # Specify the fields you want to permit for forms
+  # Foreign keys (meeting_room_id) are automatically included
+  permit_params :title, :description, :start_time, :end_time
+  
+  # Optional: Customize foreign key display and behavior
+  field :meeting_room_id do
+    title "Meeting Room"
+    foreign_key(
+      model: MeetingRoom,
+      display: :name,  # Show the 'name' field from MeetingRoom
+      null_option: "Choose a room",
+      scope: -> { MeetingRoom.available }  # Optional: only show available rooms
+    )
+  end
+  
+  # Optional: Customize other fields
+  field :title do
+    title "Meeting Title"
+    description "Enter a descriptive title for the meeting"
+  end
+  
+  field :start_time do
+    title "Start Time"
+    description "When the meeting begins"
+  end
+  
+  field :end_time do
+    title "End Time" 
+    description "When the meeting ends"
+  end
+  
+  # Optional: Hide certain fields from display
+  field :description do
+    visible false  # Won't show in index listing
+  end
+  
+  # Optional: Make fields readonly
+  field :created_at do
+    visible true
+    readonly true
+    title "Created"
+  end
+end
+
+# What happens automatically:
+#
+# 1. ElaineCrud detects that Meeting belongs_to :meeting_room
+# 2. It automatically configures meeting_room_id as a foreign key field
+# 3. In the index view, instead of showing "1, 2, 3" for meeting_room_id,
+#    it shows the related MeetingRoom's display field (usually name, title, etc.)
+# 4. In edit forms, meeting_room_id becomes a dropdown with all MeetingRoom options
+# 5. The foreign key is automatically included in permitted_params
+# 6. Database queries are optimized with includes() to avoid N+1 queries
+#
+# Manual configuration options:
+#
+# field :meeting_room_id do
+#   foreign_key(
+#     model: MeetingRoom,           # Required: the related model class
+#     display: :name,               # Field to show (default: auto-detected)
+#     scope: -> { MeetingRoom.active }, # Optional: filter available options
+#     null_option: "Select room"    # Optional: placeholder text
+#   )
+# end
+#
+# Alternative display options:
+#
+# field :meeting_room_id do
+#   foreign_key(
+#     model: MeetingRoom,
+#     display: ->(room) { "#{room.name} (#{room.capacity} seats)" }  # Proc for complex display
+#   )
+# end
+
+# Routes (add to your routes.rb):
+# resources :meetings

data/docs/FOREIGN_KEY_SUPPORT.md

@@ -0,0 +1,197 @@
+# Foreign Key Support in ElaineCrud
+
+ElaineCrud now provides comprehensive automatic support for `belongs_to` relationships in ActiveRecord models. This feature eliminates the need for manual configuration in most cases while still providing flexibility for customization.
+
+## Features
+
+### Automatic Detection
+- Automatically detects all `belongs_to` relationships in your ActiveRecord model
+- Auto-configures foreign key fields without requiring manual setup
+- Includes foreign keys in permitted parameters automatically
+- Optimizes database queries with automatic `includes()` to prevent N+1 queries
+
+### Smart Display Field Detection
+- Automatically determines the best display field for related models
+- Prefers common fields like `:name`, `:title`, `:display_name`, `:full_name`, `:label`, `:description`
+- Falls back to first string/text column if common fields aren't found
+- Uses `:id` as final fallback
+
+### Display Behavior
+- **Index View**: Shows the related record's display field instead of the foreign key ID
+- **Edit Forms**: Renders a dropdown with all available options from the related model, with the current value pre-selected
+- **Error Handling**: Gracefully handles missing records and configuration errors
+
+## Basic Usage
+
+```ruby
+class MeetingsController < ElaineCrud::BaseController
+  model Meeting  # Automatically detects belongs_to :meeting_room
+  permit_params :title, :start_time, :end_time  # meeting_room_id included automatically
+end
+```
+
+That's it! ElaineCrud will automatically:
+1. Detect the `belongs_to :meeting_room` relationship
+2. Configure `meeting_room_id` as a foreign key field
+3. Show meeting room names in the index instead of IDs
+4. Provide a dropdown in forms with all meeting rooms
+5. Include `meeting_room_id` in permitted parameters
+
+## Customization Options
+
+### Basic Customization
+```ruby
+field :meeting_room_id do
+  title "Conference Room"
+  foreign_key(
+    model: MeetingRoom,
+    display: :name,
+    null_option: "Choose a room"
+  )
+end
+```
+
+### Advanced Display Logic
+```ruby
+field :meeting_room_id do
+  foreign_key(
+    model: MeetingRoom,
+    display: ->(room) { "#{room.name} (#{room.capacity} seats)" }
+  )
+end
+```
+
+### Scoped Options
+```ruby
+field :meeting_room_id do
+  foreign_key(
+    model: MeetingRoom,
+    display: :name,
+    scope: -> { MeetingRoom.available.order(:name) }
+  )
+end
+```
+
+### Custom Method Display
+```ruby
+# In MeetingRoom model
+class MeetingRoom < ApplicationRecord
+  def display_name
+    "#{name} - #{building.name}"
+  end
+end
+
+# In controller
+field :meeting_room_id do
+  foreign_key(
+    model: MeetingRoom,
+    display: :display_name
+  )
+end
+```
+
+## Configuration Options
+
+| Option | Type | Description | Default |
+|--------|------|-------------|---------|
+| `model` | Class | The related ActiveRecord model | Auto-detected from belongs_to |
+| `display` | Symbol/Proc | Field or method to display | Auto-detected (name, title, etc.) |
+| `scope` | Proc | Limits available options | `-> { Model.all }` |
+| `null_option` | String | Placeholder text for blank option | "Select [relationship name]" |
+
+## Implementation Details
+
+### Automatic Model Analysis
+When you call `model ModelClass`, ElaineCrud:
+1. Inspects all `belongs_to` reflections on the model
+2. Creates `FieldConfiguration` objects for each foreign key
+3. Determines the best display field for each related model
+4. Adds foreign keys to the permitted parameters list
+
+### Query Optimization
+The `fetch_records` method automatically includes belongs_to associations to prevent N+1 queries:
+```ruby
+# Instead of this (N+1 queries):
+meetings.each { |meeting| puts meeting.meeting_room.name }
+
+# ElaineCrud automatically does this:
+Meeting.includes(:meeting_room).each { |meeting| puts meeting.meeting_room.name }
+```
+
+### Display Field Detection Logic
+1. Check for common display fields: `name`, `title`, `display_name`, `full_name`, `label`, `description`
+2. If none found, use first string/text column (excluding id, created_at, updated_at)
+3. Fall back to `:id` if no suitable field found
+
+## Error Handling
+
+ElaineCrud handles various error scenarios gracefully:
+- **Missing Related Record**: Shows "Not found (ID: X)" message
+- **Configuration Errors**: Shows error message in development, falls back to ID in production
+- **Missing Display Field**: Falls back to `to_s` method
+- **Database Errors**: Gracefully handles and logs errors
+
+## Migration from Manual Configuration
+
+If you previously configured foreign keys manually, ElaineCrud will respect your existing configuration:
+```ruby
+# Your existing configuration takes precedence
+field :meeting_room_id do
+  foreign_key(model: MeetingRoom, display: :custom_name)
+end
+# Auto-detection skips this field since it's already configured
+```
+
+## Performance Considerations
+
+- **Automatic Includes**: Foreign key relationships are automatically included in queries
+- **Lazy Loading**: Related records are only loaded when actually displayed
+- **Caching**: Consider adding Rails caching for frequently accessed dropdown options
+
+## Future Enhancements
+
+The current implementation focuses on `belongs_to` relationships. Future versions may include:
+- `has_many` relationship support
+- `has_and_belongs_to_many` relationship support
+- Polymorphic relationship support
+- Search/autocomplete for large datasets
+- Nested attribute support
+
+## Example Models
+
+```ruby
+class Meeting < ApplicationRecord
+  belongs_to :meeting_room
+  belongs_to :organizer, class_name: 'User'
+  
+  validates :title, presence: true
+end
+
+class MeetingRoom < ApplicationRecord
+  has_many :meetings
+  validates :name, presence: true
+end
+
+class User < ApplicationRecord
+  has_many :organized_meetings, class_name: 'Meeting', foreign_key: 'organizer_id'
+end
+```
+
+With these models, ElaineCrud automatically handles both `meeting_room_id` and `organizer_id` foreign keys in your `MeetingsController`.
+
+## Troubleshooting
+
+### Foreign Key Not Showing as Dropdown
+- Ensure your model has a `belongs_to` relationship defined
+- Check that the foreign key column exists in the database
+- Verify the related model class is accessible
+
+### Wrong Display Field Being Used
+- Manually configure the `display` option in field configuration
+- Add a custom display method to your model
+- Check model column names match expected patterns
+
+### Performance Issues
+- Add database indexes on foreign key columns
+- Consider using scopes to limit dropdown options
+- Implement caching for frequently accessed dropdowns