plutonium 0.33.1 → 0.34.0

data/docs/getting-started/tutorial/05-custom-actions.md

@@ -0,0 +1,202 @@
+# Chapter 5: Adding Custom Actions
+
+In this chapter, you'll add a "Publish" action to posts using Interactions.
+
+## What are Interactions?
+
+Interactions are classes that encapsulate business logic. They're used for:
+- Operations more complex than simple CRUD
+- Actions that need validation beyond the model
+- Operations involving multiple models
+- Business logic you want to reuse
+
+## Creating the Publish Interaction
+
+Create an interaction to publish posts:
+
+```ruby
+# packages/blogging/app/interactions/blogging/publish_post.rb
+class Blogging::PublishPost < Blogging::ResourceInteraction
+  # Presentation
+  presents label: "Publish Post",
+           icon: Phlex::TablerIcons::Send
+
+  # Having `attribute :resource` makes this a record action
+  # (shows on individual records and table rows)
+  attribute :resource
+
+  # Validation
+  validate :post_not_already_published
+
+  private
+
+  def execute
+    resource.update!(published: true, published_at: Time.current)
+
+    succeed(resource)
+      .with_message("Post published successfully!")
+  end
+
+  def post_not_already_published
+    if resource.published?
+      errors.add(:base, "Post is already published")
+    end
+  end
+end
+```
+
+## Registering the Action
+
+Add the action to the Post definition:
+
+```ruby
+# packages/blogging/app/definitions/blogging/post_definition.rb
+class Blogging::PostDefinition < Blogging::ResourceDefinition
+  # Register the publish action
+  action :publish, interaction: Blogging::PublishPost
+end
+```
+
+Action placement is automatically determined:
+- `attribute :resource` → shows on records and table rows
+- `attribute :resources` → bulk action for selected records
+- Neither → resource-level action (like "New" button)
+
+## Authorizing the Action
+
+Add permission for the action in the policy:
+
+```ruby
+# packages/blogging/app/policies/blogging/post_policy.rb
+class Blogging::PostPolicy < Blogging::ResourcePolicy
+  # ... existing permissions ...
+
+  def publish?
+    owner? && !record.published?
+  end
+end
+```
+
+## Testing the Action
+
+1. Create an unpublished post
+2. View the post details
+3. Click the "Publish" action button
+4. The post is now published
+
+## Actions with User Input
+
+Let's create a more complex action - scheduling publication:
+
+```ruby
+# packages/blogging/app/interactions/blogging/schedule_post.rb
+class Blogging::SchedulePost < Blogging::ResourceInteraction
+  presents label: "Schedule Publication",
+           icon: Phlex::TablerIcons::Calendar
+
+  attribute :resource
+  attribute :publish_at, :datetime
+
+  # Define form input
+  input :publish_at, as: :datetime
+
+  # Validations
+  validates :publish_at, presence: true
+  validate :publish_at_in_future
+
+  private
+
+  def execute
+    resource.update!(
+      scheduled_at: publish_at,
+      published: false
+    )
+
+    succeed(resource)
+      .with_message("Post scheduled for #{publish_at.strftime('%B %d, %Y at %I:%M %p')}")
+  end
+
+  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
+```
+
+Register it:
+
+```ruby
+# In PostDefinition
+action :schedule, interaction: Blogging::SchedulePost
+```
+
+Because the interaction defines an `input`, users see a form to select the publication date.
+
+## Resource-Level Actions
+
+Actions can operate at the resource level (not on a specific record):
+
+```ruby
+# packages/blogging/app/interactions/blogging/import_posts.rb
+class Blogging::ImportPosts < Blogging::ResourceInteraction
+  presents label: "Import Posts",
+           icon: Phlex::TablerIcons::Upload
+
+  attribute :file
+
+  input :file, as: :file
+
+  validates :file, presence: true
+
+  private
+
+  def execute
+    # Process CSV file...
+    succeed(nil).with_message("Posts imported successfully")
+  end
+end
+```
+
+Register it:
+
+```ruby
+action :import, interaction: Blogging::ImportPosts
+```
+
+Since `ImportPosts` has no `attribute :resource` or `attribute :resources`, it automatically becomes a resource-level action.
+
+## Action Placement
+
+For **interactive actions**, placement is auto-determined from attributes:
+
+| Attribute | Placement |
+|-----------|-----------|
+| `attribute :resource` | Record show page + table rows |
+| `attribute :resources` | Bulk action (selected records) |
+| Neither | Resource-level (like "New" button) |
+
+You can override with explicit options if needed:
+
+| Option | Location |
+|--------|----------|
+| `record_action:` | Record show page |
+| `collection_record_action:` | Table row actions |
+| `resource_action:` | Above the table |
+
+## Action Styling
+
+Customize action appearance:
+
+```ruby
+action :archive,
+       interaction: ArchivePost,
+       category: :danger,            # red styling
+       confirmation: "Are you sure?" # confirmation dialog
+```
+
+## What's Next
+
+We have posts with custom actions. In the next chapter, we'll add Comments as a nested resource.
+
+[Continue to Chapter 6: Nested Resources →](./06-nested-resources)

data/docs/getting-started/tutorial/06-nested-resources.md

@@ -0,0 +1,147 @@
+# Chapter 6: Nested Resources
+
+In this chapter, you'll add Comments as a nested resource under Posts.
+
+## What are Nested Resources?
+
+Nested resources are resources that belong to a parent resource. In our blog:
+- Comments belong to Posts
+- The URL reflects this: `/admin/blogging/posts/1/blogging/comments`
+- Comments are automatically scoped to their parent post
+
+## Generating the Comment Resource
+
+```bash
+rails generate pu:res:scaffold Comment body:text user:belongs_to Blogging/Post:belongs_to --dest=blogging
+```
+
+## Setting Up the Association
+
+Update the Post model to add the `has_many` association:
+
+```ruby
+# packages/blogging/app/models/blogging/post.rb
+class Blogging::Post < Blogging::ResourceRecord
+  belongs_to :user
+  has_many :comments, foreign_key: :post_id, dependent: :destroy
+  # ... existing code
+end
+```
+
+## The Comment Model
+
+The generator creates:
+
+```ruby
+# packages/blogging/app/models/blogging/comment.rb
+class Blogging::Comment < Blogging::ResourceRecord
+  belongs_to :user
+  belongs_to :post, class_name: "Blogging::Post"
+  # ... generated code
+end
+```
+
+Note: When referencing resources within the same package, the generator uses the short name (`:post`) while setting the appropriate `class_name` and foreign key to the correct table.
+
+## Connecting to the Portal
+
+Connect comments to the admin portal:
+
+```bash
+rails generate pu:res:conn Blogging::Comment --dest=admin_portal
+```
+
+Because `Comment` has `belongs_to :post`, Plutonium automatically creates nested routes:
+- `GET /admin/blogging/posts/:blogging_post_id/blogging/comments`
+- `POST /admin/blogging/posts/:blogging_post_id/blogging/comments`
+- `GET /admin/blogging/posts/:blogging_post_id/blogging/comments/:id`
+
+## Showing Comments on Post Detail
+
+To show a comments panel on the post detail page, add `comments` to `permitted_associations` in the policy:
+
+```ruby
+# packages/blogging/app/policies/blogging/post_policy.rb
+class Blogging::PostPolicy < Blogging::ResourcePolicy
+  def permitted_associations
+    %i[user comments]
+  end
+end
+```
+
+The panel links to the nested comments route and shows "Add Comment" if the user has permission.
+
+## Comment Policy
+
+Add authorization for comments:
+
+```ruby
+# packages/blogging/app/policies/blogging/comment_policy.rb
+class Blogging::CommentPolicy < Blogging::ResourcePolicy
+  def read?
+    true # Anyone can read comments
+  end
+
+  def create?
+    true # Anyone authenticated can comment
+  end
+
+  def update?
+    owner?
+  end
+
+  def destroy?
+    owner? || post_owner?
+  end
+
+  # Scope to comments on published posts (or user's own posts)
+  def relation_scope(relation)
+    relation.joins(:post).where(
+      blogging_posts: {published: true}
+    ).or(
+      relation.where(user_id: user.id)
+    )
+  end
+
+  private
+
+  def owner?
+    record.user_id == user.id
+  end
+
+  def post_owner?
+    record.post.user_id == user.id
+  end
+end
+```
+
+## Nested Forms
+
+You can edit comments directly on the post form using nested attributes:
+
+```ruby
+# In Post model
+accepts_nested_attributes_for :comments, allow_destroy: true
+```
+
+```ruby
+# In PostDefinition - option 1: inline block
+nested_input :comments do |definition|
+  definition.input :body
+end
+
+# In PostDefinition - option 2: use existing definition
+nested_input :comments, using: Blogging::CommentDefinition, fields: %i[body]
+```
+
+This adds an inline comments editor to the post form.
+
+## Nesting Limitations
+
+Plutonium supports one level of nesting. For deeper hierarchies (e.g., Replies to Comments), keep URLs flat: `/blogging/comments/:blogging_comment_id/blogging/replies`
+
+## What's Next
+
+Our blog has posts and comments. In the final chapter, we'll customize the UI to make it look polished.
+
+[Continue to Chapter 7: Customizing the UI →](./07-customizing-ui)

data/docs/getting-started/tutorial/07-customizing-ui.md

@@ -0,0 +1,254 @@
+# Chapter 7: Customizing the UI
+
+In this chapter, you'll customize forms, tables, and pages to create a polished interface.
+
+## Customizing Fields
+
+Fields control how attributes appear in forms and displays. Plutonium auto-infers fields from your model, so you only need to declare fields when customizing their behavior.
+
+### Field Types
+
+```ruby
+# packages/blogging/app/definitions/blogging/post_definition.rb
+class Blogging::PostDefinition < Blogging::ResourceDefinition
+  # Rich text editor instead of plain textarea
+  field :body, as: :rich_text
+
+  # Select with predefined options
+  input :status, as: :select, choices: %w[draft review published]
+end
+```
+
+### Conditional Fields
+
+Show fields based on conditions:
+
+```ruby
+# Only show published_at when published is true
+field :published_at, condition: -> { object.published? }
+
+# Show different fields for new vs existing records
+field :author, condition: :new_record?
+```
+
+## Customizing Tables
+
+Columns are auto-inferred from your model. Only declare columns when customizing their behavior.
+
+### Column Configuration
+
+```ruby
+# Custom label and sortable
+column :user, label: "Author", sortable: true
+
+# Computed column with block
+column :comment_count do |post|
+  post.comments.count
+end
+```
+
+### Table Actions
+
+```ruby
+# Show page actions
+action :publish, interaction: Blogging::PublishPost, record_action: true
+
+# Table row actions
+action :archive, interaction: Blogging::ArchivePost, collection_record_action: true
+
+# Index page actions
+action :import, interaction: Blogging::ImportPosts, resource_action: true
+
+# Bulk actions (selected records)
+action :bulk_publish, interaction: Blogging::BulkPublish, bulk_action: true
+```
+
+## Customizing Search and Filters
+
+```ruby
+# Search configuration
+search do |scope, query|
+  scope.where("title ILIKE ? OR body ILIKE ?", "%#{query}%", "%#{query}%")
+end
+
+# Predefined scopes (reference model scopes)
+scope :published, default: true  # Applied by default, uses Post.published
+scope :drafts                    # Uses Post.draft
+
+# Inline scope with block
+scope(:recent) { |scope| scope.where('created_at > ?', 1.week.ago) }
+
+# Inline scope with controller context
+scope(:mine) { |scope| scope.where(user: current_user) }
+
+# Filters
+filter :title, with: Plutonium::Query::Filters::Text, predicate: :contains
+filter :status, with: Plutonium::Query::Filters::Text, predicate: :eq
+
+# Custom filter with lambda
+filter :published, with: ->(scope, value) {
+  value == "true" ? scope.where.not(published_at: nil) : scope.where(published_at: nil)
+}
+
+# Sorting options
+sort :title
+sort :created_at
+sort :published
+
+# Default sort
+default_sort :created_at, :desc
+```
+
+## Custom Page Classes
+
+Override page title and description in definitions:
+
+```ruby
+class Blogging::PostDefinition < Blogging::ResourceDefinition
+  # Custom page titles
+  index_page_title "Blog Posts"
+  index_page_description "Manage your blog content"
+
+  show_page_title { |record| record.title }
+  show_page_description "View post details"
+end
+```
+
+For more advanced customization, you can create custom page classes that inherit from Plutonium's page components:
+
+```ruby
+# packages/admin_portal/app/views/admin_portal/blogging/posts/index_page.rb
+class AdminPortal::Blogging::Posts::IndexPage < Blogging::PostDefinition::IndexPage
+  private
+
+  def page_title
+    "Blog Posts"
+  end
+
+  def page_description
+    "Manage your blog content"
+  end
+
+  # Add content after the page header
+  def render_after_page_header
+    div(class: "mb-4 p-4 bg-blue-50 rounded") do
+      p { "Custom content here" }
+    end
+  end
+end
+```
+
+## Custom Form Layout
+
+Control form layout using wrapper options in definitions:
+
+```ruby
+class Blogging::PostDefinition < Blogging::ResourceDefinition
+  # Full-width fields
+  input :title, wrapper: {class: "col-span-full"}
+  input :body, as: :rich_text, wrapper: {class: "col-span-full"}
+
+  # Side-by-side fields (default is col-span-full)
+  input :published_at, wrapper: {class: "col-span-1"}
+  input :category, wrapper: {class: "col-span-1"}
+end
+```
+
+For advanced form customization, use the block syntax:
+
+```ruby
+input :birth_date do |f|
+  f.date_tag(min: 18.years.ago.to_date)
+end
+```
+
+## Theming with TailwindCSS
+
+Plutonium uses TailwindCSS 4. Customize the theme:
+
+```css
+/* app/assets/stylesheets/application.css */
+@import "tailwindcss";
+@import "gem:plutonium/src/css/plutonium.css";
+
+@theme {
+  --color-primary-500: #6366f1;  /* Indigo */
+  --color-primary-600: #4f46e5;
+  --color-primary-700: #4338ca;
+
+  --radius-md: 0.5rem;
+  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+}
+```
+
+## Custom Components
+
+Create reusable components with Phlex:
+
+```ruby
+# app/components/status_badge.rb
+class StatusBadge < Plutonium::UI::Component::Base
+  def initialize(published:)
+    @published = published
+  end
+
+  def view_template
+    if @published
+      span(class: "px-2 py-1 text-xs bg-green-100 text-green-800 rounded") { "Published" }
+    else
+      span(class: "px-2 py-1 text-xs bg-yellow-100 text-yellow-800 rounded") { "Draft" }
+    end
+  end
+end
+
+# Use in definition
+column :status do |post|
+  render StatusBadge.new(published: post.published?)
+end
+```
+
+## Layout Customization
+
+Layouts are Phlex components that wrap page content. The base layout provides hooks for customization:
+
+```ruby
+class CustomLayout < Plutonium::UI::Layout::ResourceLayout
+  private
+
+  # Customize body classes
+  def body_attributes
+    {class: "antialiased min-h-screen bg-white dark:bg-gray-900"}
+  end
+
+  # Add content before the main section
+  def render_before_main
+    super
+    # Add custom header content
+  end
+
+  # Add content after the main section
+  def render_after_main
+    super
+    # Add custom footer content
+  end
+end
+```
+
+See the [Theming Guide](/guides/theming) for comprehensive customization options.
+
+## What's Next
+
+Congratulations! You've built a complete blog application with:
+- Resource CRUD operations
+- Authentication with Rodauth
+- Authorization with policies
+- Custom actions with Interactions
+- Nested resources
+- Customized UI
+
+Continue exploring:
+- [Guides](/guides/) - Deep dives on specific topics
+- [Reference](/reference/) - Complete API documentation
+- [Cookbook](/cookbook/) - Real-world recipes
+
+Happy building with Plutonium!

data/docs/getting-started/tutorial/index.md

@@ -0,0 +1,64 @@
+# Tutorial: Building a Blog
+
+In this tutorial, you'll build a complete blog application with Plutonium. You'll learn:
+
+- How to structure a Plutonium application
+- Creating resources with models, definitions, and policies
+- Setting up authentication with Rodauth
+- Implementing authorization rules
+- Adding custom actions with Interactions
+- Customizing the UI
+
+## What We'll Build
+
+A blog application with:
+- **Posts** - Articles with title, body, and publication status
+- **Comments** - Nested under posts
+- **Users** - Authors who can manage their own posts
+- **Admin Portal** - Full access for administrators
+- **Author Portal** - Limited access for content authors
+
+## Prerequisites
+
+- Ruby 3.2+
+- Rails 8.0+ (or 7.1+)
+- Node.js 18+
+- PostgreSQL (or SQLite for development)
+
+## Time Required
+
+This tutorial takes approximately 45-60 minutes to complete.
+
+## Chapters
+
+### [1. Project Setup](./01-setup)
+Create a new Plutonium application and understand the project structure.
+
+### [2. Creating Your First Resource](./02-first-resource)
+Generate the Post resource with model, definition, policy, and controller.
+
+### [3. Setting Up Authentication](./03-authentication)
+Configure Rodauth for user authentication with multiple account types.
+
+### [4. Implementing Authorization](./04-authorization)
+Add policies to control who can view, create, edit, and delete posts.
+
+### [5. Adding Custom Actions](./05-custom-actions)
+Create a "Publish" action using Interactions for business logic.
+
+### [6. Nested Resources](./06-nested-resources)
+Add Comments as a nested resource under Posts.
+
+### [7. Customizing the UI](./07-customizing-ui)
+Customize forms, tables, and views to match your requirements.
+
+## Getting Help
+
+If you get stuck:
+- Check the [Guides](/guides/) for detailed explanations
+- Browse the [Reference Documentation](/reference/) for API details
+- Visit our [GitHub Issues](https://github.com/radioactive-labs/plutonium-core/issues)
+
+Let's get started!
+
+[Begin Chapter 1: Project Setup →](./01-setup)