plutonium 0.50.0 → 0.51.0

data/docs/reference/interaction/index.md

@@ -1,449 +0,0 @@
-# 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
-```
-
-::: warning Handle RecordInvalid
-`ActiveRecord::RecordInvalid` is **not** rescued automatically. Always rescue it when using bang methods (`create!`, `update!`, `save!`).
-:::
-
-## 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
-
-::: tip Automatic Redirect
-On success, the controller automatically redirects to the resource.
-:::
-
-### Basic Success
-
-```ruby
-succeed(resource)  # Redirects to resource automatically
-```
-
-### With Message
-
-```ruby
-succeed(resource).with_message("Post published!")
-succeed(resource).with_message("Warning: limited visibility", :alert)
-```
-
-### With Custom Redirect
-
-Useful when redirecting somewhere other than the default:
-
-```ruby
-succeed(resource).with_redirect_response(custom_dashboard_path)
-```
-
-### 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}")
-  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()`
-
-## 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

@@ -1,248 +0,0 @@
-# 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)