plutonium 0.33.1 → 0.34.0

data/docs/reference/interaction/index.md

@@ -0,0 +1,445 @@
+# Interaction Reference
+
+Complete reference for business logic Interactions.
+
+## Overview
+
+Interactions encapsulate business logic for custom actions. They:
+- Accept input from users
+- Validate that input
+- Execute business logic
+- Return success or failure outcomes
+
+## Base Class
+
+```ruby
+# app/interactions/resource_interaction.rb (generated during install)
+class ResourceInteraction < Plutonium::Resource::Interaction
+end
+
+# app/interactions/publish_post_interaction.rb
+class PublishPostInteraction < ResourceInteraction
+  # Interaction code
+end
+```
+
+## Presentation
+
+Configure how the action appears in the UI:
+
+```ruby
+class PublishPost < Plutonium::Resource::Interaction
+  presents label: "Publish Post",
+           icon: Phlex::TablerIcons::Send,
+           description: "Make this post visible to the public"
+end
+```
+
+Access presentation metadata:
+
+```ruby
+PublishPost.label       # => "Publish Post"
+PublishPost.icon        # => Phlex::TablerIcons::Send
+PublishPost.description # => "Make this post visible..."
+```
+
+## Attributes
+
+Define inputs using ActiveModel attributes:
+
+### Basic Types
+
+```ruby
+attribute :title, :string
+attribute :count, :integer
+attribute :price, :decimal
+attribute :active, :boolean
+attribute :published_at, :datetime
+```
+
+### With Defaults
+
+```ruby
+attribute :status, :string, default: "pending"
+attribute :notify, :boolean, default: true
+attribute :count, :integer, default: 1
+attribute :created_at, :datetime, default: -> { Time.current }
+```
+
+### The resource Attribute
+
+For record actions, declare a `resource` attribute:
+
+```ruby
+class PublishPost < Plutonium::Resource::Interaction
+  attribute :resource  # The record being acted upon
+
+  private
+
+  def execute
+    resource.update!(published: true)
+    succeed(resource)
+  end
+end
+```
+
+### The resources Attribute
+
+For bulk actions, declare a `resources` attribute:
+
+```ruby
+class BulkArchive < Plutonium::Resource::Interaction
+  attribute :resources  # Collection of records
+
+  private
+
+  def execute
+    resources.update_all(archived: true)
+    succeed(resources)
+  end
+end
+```
+
+## Form Inputs
+
+Define how attributes render in forms using the `input` method:
+
+```ruby
+class InviteUser < Plutonium::Resource::Interaction
+  attribute :resource
+  attribute :email, :string
+  attribute :role, :string
+
+  input :email, as: :email
+  input :role, as: :select, choices: %w[admin member viewer]
+end
+```
+
+See [Fields Reference](/reference/definition/fields) for all input types and options.
+
+## Validation
+
+Use standard ActiveModel validations:
+
+```ruby
+class SchedulePost < Plutonium::Resource::Interaction
+  attribute :resource
+  attribute :publish_at, :datetime
+
+  validates :publish_at, presence: true
+  validate :publish_at_in_future
+
+  private
+
+  def publish_at_in_future
+    if publish_at.present? && publish_at <= Time.current
+      errors.add(:publish_at, "must be in the future")
+    end
+  end
+end
+```
+
+Validations run automatically before `execute`. If invalid, returns a failure outcome.
+
+## The execute Method
+
+Main logic goes here. Must return an outcome using `succeed()` or `failed()`:
+
+```ruby
+private
+
+def execute
+  resource.update!(published: true)
+  succeed(resource).with_message("Published!")
+rescue ActiveRecord::RecordInvalid => e
+  failed(e.record.errors)
+end
+```
+
+## Constructor
+
+Interactions require `view_context:` and accept attributes as keyword arguments:
+
+```ruby
+interaction = PublishPost.new(
+  view_context: view_context,
+  resource: post,
+  notify: true
+)
+```
+
+The controller handles this automatically for interactive actions.
+
+## Calling Interactions
+
+### Via call Class Method
+
+```ruby
+outcome = PublishPost.call(view_context: view_context, resource: post)
+
+if outcome.success?
+  # Handle success
+else
+  # Handle failure
+end
+```
+
+### Via call Instance Method
+
+```ruby
+interaction = PublishPost.new(view_context: view_context, resource: post)
+outcome = interaction.call
+```
+
+## Success Outcomes
+
+### Basic Success
+
+```ruby
+succeed(resource)
+```
+
+### With Message
+
+```ruby
+succeed(resource).with_message("Post published!")
+succeed(resource).with_message("Warning: limited visibility", :alert)
+```
+
+### With Redirect
+
+```ruby
+succeed(resource).with_redirect_response(posts_path)
+succeed(resource).with_redirect_response(resource, status: :see_other)
+```
+
+### With File Download
+
+```ruby
+succeed(resource).with_file_response(file_path, filename: "report.pdf")
+```
+
+### With Render
+
+```ruby
+succeed(resource).with_render_response(:custom_template)
+```
+
+### Chaining
+
+```ruby
+succeed(resource)
+  .with_message("Created!")
+  .with_redirect_response(edit_post_path(resource))
+```
+
+## Failure Outcomes
+
+### Simple Failure
+
+```ruby
+failed("Cannot publish draft posts")
+```
+
+### With Attribute
+
+```ruby
+failed("is invalid", :email)
+```
+
+### With Hash of Errors
+
+```ruby
+failed(email: "is invalid", name: "is required")
+```
+
+### With ActiveModel Errors
+
+```ruby
+failed(resource.errors)
+```
+
+### Manual Error Addition
+
+```ruby
+def execute
+  errors.add(:base, "Post must have content")
+  return failure if errors.any?
+
+  # Continue...
+end
+```
+
+## Chaining Interactions
+
+Use `and_then` to chain operations. On failure, the chain short-circuits:
+
+```ruby
+def execute
+  CreateUserInteraction.call(view_context:, **user_params)
+    .and_then { |result| SendWelcomeEmail.call(view_context:, user: result.value) }
+    .and_then { |result| LogActivity.call(view_context:, user: result.value) }
+    .with_message("User created and welcomed!")
+end
+```
+
+## Accessing Current User
+
+```ruby
+def execute
+  resource.update!(updated_by: current_user)
+  succeed(resource)
+end
+
+# current_user is provided by the base class:
+# def current_user
+#   view_context.controller.helpers.current_user
+# end
+```
+
+## Complete Example
+
+```ruby
+class Company::InviteUserInteraction < Plutonium::Resource::Interaction
+  presents label: "Invite User",
+           icon: Phlex::TablerIcons::UserPlus,
+           description: "Send an invitation email"
+
+  attribute :resource  # The company
+  attribute :email, :string
+  attribute :role, :string
+
+  input :email, as: :email
+  input :role, as: :select, choices: -> { UserInvite.roles.keys }
+
+  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :role, presence: true, inclusion: { in: UserInvite.roles.keys }
+  validate :not_already_invited
+
+  private
+
+  def execute
+    invite = UserInvite.create!(
+      company: resource,
+      email: email,
+      role: role,
+      invited_by: current_user
+    )
+    UserInviteMailer.invitation(invite).deliver_later
+
+    succeed(resource)
+      .with_message("Invitation sent to #{email}")
+      .with_redirect_response(resource)
+  rescue ActiveRecord::RecordInvalid => e
+    failed(e.record.errors)
+  end
+
+  def not_already_invited
+    return unless email.present?
+
+    if UserInvite.exists?(company: resource, email: email, state: :pending)
+      errors.add(:email, "already has a pending invitation")
+    end
+  end
+end
+```
+
+## Connecting to Definitions
+
+Register interactions as actions in definitions:
+
+```ruby
+class PostDefinition < Plutonium::Resource::Definition
+  action :publish, interaction: PublishPostInteraction
+  action :invite_user, interaction: InviteUserInteraction
+
+  action :archive,
+    interaction: ArchiveInteraction,
+    confirmation: "Are you sure?",
+    category: :danger,
+    position: 100
+end
+```
+
+## Immediate vs Form Actions
+
+Plutonium determines if an action needs a form based on whether inputs are defined:
+
+**Shows form first** (has inputs):
+
+```ruby
+class InviteUserInteraction < Plutonium::Resource::Interaction
+  attribute :resource
+  attribute :email
+  input :email  # This triggers form display
+end
+```
+
+**Executes immediately** (no inputs):
+
+```ruby
+class ArchiveInteraction < Plutonium::Resource::Interaction
+  attribute :resource
+  # No inputs = immediate execution with confirmation
+end
+```
+
+## Policy Integration
+
+Control access with policy methods matching the action name:
+
+```ruby
+class PostPolicy < Plutonium::Resource::Policy
+  def publish?
+    update? && record.draft?
+  end
+
+  def archive?
+    destroy? && !record.archived?
+  end
+end
+```
+
+## Testing
+
+```ruby
+RSpec.describe PublishPost do
+  let(:view_context) { double("view_context", controller: double(helpers: double(current_user: user))) }
+  let(:user) { create(:user) }
+  let(:post) { create(:post, user: user, published: false) }
+
+  describe '#call' do
+    it 'publishes the post' do
+      interaction = described_class.new(view_context: view_context, resource: post)
+      outcome = interaction.call
+
+      expect(outcome).to be_success
+      expect(post.reload).to be_published
+    end
+
+    context 'when validation fails' do
+      it 'returns failure outcome' do
+        interaction = described_class.new(view_context: view_context, resource: nil)
+        outcome = interaction.call
+
+        expect(outcome).to be_failure
+      end
+    end
+  end
+end
+```
+
+## Best Practices
+
+1. **Keep interactions focused** - One action per interaction
+2. **Use validations** - Validate all inputs before execution
+3. **Handle errors gracefully** - Rescue exceptions and return `failed()`
+4. **Return meaningful messages** - Help users understand what happened
+5. **Use `and_then` for chains** - Compose complex workflows from simple interactions
+6. **Declare attributes explicitly** - Always declare `resource` or `resources` attributes
+
+## Related
+
+- [Actions Reference](/reference/definition/actions) - Connecting interactions to definitions
+- [Fields Reference](/reference/definition/fields) - Input configuration
+- [Policy Reference](/reference/policy/) - Authorization

data/docs/reference/model/features.md

@@ -0,0 +1,248 @@
+# Model Features
+
+Features provided by `Plutonium::Resource::Record`.
+
+## has_cents
+
+Store monetary values as integers (cents) while exposing decimal accessors.
+
+```ruby
+class Product < ResourceRecord
+  # Column: price_cents (integer)
+  # Generates: price (decimal accessor)
+  has_cents :price_cents
+end
+```
+
+### Usage
+
+```ruby
+product = Product.new
+product.price = 19.99
+product.price_cents  # => 1999
+
+product.price_cents = 2500
+product.price  # => 25.0
+```
+
+### Options
+
+```ruby
+class Order < ResourceRecord
+  # Default: rate 100 (cents to dollars)
+  has_cents :subtotal_cents
+
+  # Custom name for the accessor
+  has_cents :cost_cents, name: :wholesale_price
+  # cost_cents column, wholesale_price accessor
+
+  # Yen or other currencies without subunits (rate: 1)
+  has_cents :price_yen, name: :price_jpy, rate: 1
+
+  # Higher precision (e.g., 1000 units per dollar)
+  has_cents :amount_cents, rate: 1000
+
+  # Custom suffix when name matches column pattern
+  has_cents :total_cents, suffix: "value"
+  # Generates: total_value accessor
+end
+```
+
+### Validation Inheritance
+
+Validations on the cents column propagate to the decimal accessor:
+
+```ruby
+class Product < ResourceRecord
+  has_cents :price_cents
+  validates :price_cents, numericality: { greater_than_or_equal_to: 0 }
+end
+
+product = Product.new(price: -10)
+product.valid?              # => false
+product.errors[:price_cents] # => ["must be greater than or equal to 0"]
+product.errors[:price]       # => ["is invalid"]
+```
+
+### Reflection
+
+```ruby
+Product.has_cents_attributes
+# => { price_cents: { name: :price, rate: 100 } }
+
+Product.has_cents_attribute?(:price_cents)  # => true
+Product.has_cents_attribute?(:name)         # => false
+```
+
+## Labeling
+
+The `to_label` method provides a human-readable representation for dropdowns and displays:
+
+```ruby
+post.to_label  # => "My Post Title"
+user.to_label  # => "John Doe"
+```
+
+### Resolution Order
+
+1. Returns `name` attribute if present
+2. Returns `title` attribute if present
+3. Falls back to `"ModelName #id"`
+
+```ruby
+class Post < ResourceRecord
+  # Has title column
+end
+
+post = Post.new(title: "Hello World")
+post.to_label  # => "Hello World"
+
+post.title = nil
+post.to_label  # => "Post #123"
+```
+
+## Route Parameters
+
+Customize how records appear in URLs.
+
+### Static Parameter
+
+Use a specific column for URLs:
+
+```ruby
+class Post < ResourceRecord
+  path_parameter :slug
+end
+```
+
+```ruby
+post = Post.create(slug: "hello-world")
+post.to_param  # => "hello-world"
+
+# URL: /posts/hello-world
+Post.from_path_param("hello-world")  # Finds by slug
+```
+
+### Dynamic Parameter
+
+Combine ID with a readable slug:
+
+```ruby
+class Post < ResourceRecord
+  dynamic_path_parameter :title
+end
+```
+
+```ruby
+post = Post.create(id: 42, title: "Hello World")
+post.to_param  # => "42-hello-world"
+
+# URL: /posts/42-hello-world
+Post.from_path_param("42-hello-world")  # Extracts ID, finds by id
+```
+
+## Secure Association SGIDs
+
+Associations automatically get Signed Global ID accessors for secure form handling.
+
+### Singular Associations (belongs_to, has_one)
+
+```ruby
+class Post < ResourceRecord
+  belongs_to :author
+end
+```
+
+Generates:
+
+```ruby
+post.author_sgid       # => SignedGlobalID for the author
+post.author_sgid = sgid  # Locates and assigns author from SGID
+```
+
+### Collection Associations (has_many)
+
+```ruby
+class Post < ResourceRecord
+  has_many :tags
+end
+```
+
+Generates:
+
+```ruby
+post.tag_sgids                    # => Array of SignedGlobalIDs
+post.tag_sgids = [sgid1, sgid2]   # Locates and assigns tags from SGIDs
+post.add_tag_sgid(sgid)           # Add a single tag by SGID
+post.remove_tag_sgid(sgid)        # Remove a single tag by SGID
+```
+
+### Use Case
+
+These methods enable secure association inputs in forms without exposing database IDs:
+
+```ruby
+# In form
+f.secure_association_tag  # Uses SGIDs instead of IDs
+```
+
+## associated_with Scope
+
+Finds records associated with a given parent. Used internally for nested resource scoping.
+
+```ruby
+Comment.associated_with(post)  # Comments belonging to post
+```
+
+### Resolution Order
+
+1. Checks for custom scope: `associated_with_#{model_name}`
+2. Finds direct association from self to record
+3. Finds reverse association from record to self (with performance warning)
+4. Raises error with helpful message
+
+### Custom Scope
+
+For complex relationships, define a named scope:
+
+```ruby
+class Comment < ResourceRecord
+  # Comments belong to posts, which belong to organizations
+  scope :associated_with_organization, ->(org) {
+    joins(:post).where(posts: { organization_id: org.id })
+  }
+end
+```
+
+## Field Name Introspection
+
+Class methods for discovering model fields by type:
+
+```ruby
+Post.resource_field_names           # All fields suitable for forms/displays
+Post.content_column_field_names     # Database content columns
+Post.belongs_to_association_field_names  # belongs_to associations
+Post.has_one_association_field_names     # has_one associations (excluding attachments)
+Post.has_many_association_field_names    # has_many associations (excluding attachments)
+Post.has_one_attached_field_names        # Single file attachments
+Post.has_many_attached_field_names       # Multiple file attachments
+```
+
+These methods are cached in non-local environments for performance.
+
+## Nested Attributes Introspection
+
+```ruby
+Post.all_nested_attributes_options
+# => {
+#   comments: { allow_destroy: true, limit: 10, macro: :has_many, class: Comment },
+#   metadata: { update_only: true, macro: :has_one, class: PostMetadata }
+# }
+```
+
+Returns configuration for all associations with `accepts_nested_attributes_for`.
+
+## Related
+
+- [Model Reference](./index)
+- [Nested Resources Guide](/guides/nested-resources)