anima-core 0.3.0 → 1.0.0

data/skills/draper-decorators/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: draper-decorators
+description: "Draper decorator patterns for Rails views. Activate when creating or testing decorators, moving formatting logic out of models/views, editing *_decorator.rb files, or working in app/decorators/."
+---
+
+# Draper Decorators for Rails
+
+This skill provides guidance for creating effective Draper decorators in Rails applications.
+
+## Philosophy
+
+Decorators implement separation of concerns between **business logic** (models) and **presentation logic** (views). A decorator wraps a model to add view-specific methods without polluting the model.
+
+**What belongs in decorators:**
+- Date/time formatting (`created_at.strftime("%B %d, %Y")`)
+- String concatenation (`"#{first_name} #{last_name}"`)
+- HTML generation (`h.content_tag(:span, status, class: css_class)`)
+- Conditional rendering based on state
+- Number formatting (currency, percentages)
+- CSS class generation based on object state
+
+**What does NOT belong in decorators:**
+- Business logic (validations, calculations, state changes)
+- Database queries (use includes in controllers)
+- Anything not directly related to presentation
+
+## Basic Structure
+
+```ruby
+# app/decorators/user_decorator.rb
+class UserDecorator < ApplicationDecorator
+  delegate_all
+
+  def full_name
+    "#{first_name} #{last_name}"
+  end
+
+  def formatted_created_at
+    created_at.strftime("%B %d, %Y")
+  end
+
+  def status_badge
+    css_class = active? ? "badge-success" : "badge-secondary"
+    h.content_tag(:span, status, class: "badge #{css_class}")
+  end
+end
+```
+
+## Delegation Strategies
+
+### Option 1: `delegate_all` (Convenient)
+
+Delegates all methods to the wrapped object via `method_missing`. Use for most decorators.
+
+```ruby
+class ProductDecorator < ApplicationDecorator
+  delegate_all
+
+  def formatted_price
+    h.number_to_currency(price)
+  end
+end
+```
+
+### Option 2: Explicit Delegation (Strict)
+
+Explicitly declare which methods to delegate. Use for larger apps where control matters.
+
+```ruby
+class ProductDecorator < ApplicationDecorator
+  delegate :id, :name, :price, :created_at, :persisted?
+
+  def formatted_price
+    h.number_to_currency(price)
+  end
+end
+```
+
+## Accessing the Wrapped Object
+
+Three equivalent ways to access the model:
+
+```ruby
+class ArticleDecorator < ApplicationDecorator
+  delegate_all
+
+  def display_title
+    object.title.upcase      # via 'object'
+    model.title.upcase       # via 'model' (alias)
+    article.title.upcase     # via model name (auto-generated)
+  end
+end
+```
+
+## Accessing Rails Helpers
+
+Use `h` or `helpers` to access view helpers:
+
+```ruby
+class PostDecorator < ApplicationDecorator
+  delegate_all
+
+  def formatted_body
+    h.simple_format(body)
+  end
+
+  def edit_link
+    h.link_to("Edit", h.edit_post_path(object), class: "btn")
+  end
+
+  def publication_date
+    h.l(published_at, format: :long)  # l is localize alias
+  end
+end
+```
+
+## Decorating in Controllers
+
+Decorate **at the last moment**, right before rendering:
+
+```ruby
+class PostsController < ApplicationController
+  def show
+    @post = Post.find(params[:id]).decorate
+  end
+
+  def index
+    @posts = Post.includes(:author).all.decorate
+  end
+end
+```
+
+**Critical:** Always use `includes` BEFORE decorating to avoid N+1 queries.
+
+## Association Decoration
+
+Use `decorates_association` to auto-decorate associations:
+
+```ruby
+class PostDecorator < ApplicationDecorator
+  delegate_all
+  decorates_association :author
+  decorates_association :comments
+  decorates_association :recent_comments, scope: :recent
+end
+```
+
+In views, `@post.author` returns `AuthorDecorator`, not `Author`.
+
+## Context Passing
+
+Pass extra data to decorators via context:
+
+```ruby
+# Controller
+@product = Product.find(params[:id]).decorate(context: { current_user: })
+
+# Decorator
+class ProductDecorator < ApplicationDecorator
+  delegate_all
+
+  def admin_price_info
+    return unless context[:current_user]&.admin?
+    "Cost: #{h.number_to_currency(cost)} | Margin: #{margin}%"
+  end
+end
+```
+
+## Collection Decoration
+
+```ruby
+# Auto-infers decorator from model
+@products = Product.all.decorate
+
+# Explicit decorator
+@products = ProductDecorator.decorate_collection(Product.all)
+
+# With pagination (use custom collection decorator)
+class PaginatingDecorator < Draper::CollectionDecorator
+  delegate :current_page, :total_pages, :limit_value
+end
+
+class ProductDecorator < ApplicationDecorator
+  def self.collection_decorator_class
+    PaginatingDecorator
+  end
+end
+```
+
+## Testing Decorators
+
+Place specs in `spec/decorators/`. Draper auto-configures RSpec integration.
+
+### Basic Pattern
+
+```ruby
+# spec/decorators/user_decorator_spec.rb
+require 'rails_helper'
+
+RSpec.describe UserDecorator do
+  subject(:decorator) { described_class.new(user) }
+
+  let(:user) { build_stubbed(:user, first_name: "John", last_name: "Doe") }
+
+  describe "#full_name" do
+    subject(:full_name) { decorator.full_name }
+
+    it "combines first and last name" do
+      expect(full_name).to eq("John Doe")
+    end
+  end
+
+  describe "#formatted_created_at" do
+    subject(:formatted_date) { decorator.formatted_created_at }
+
+    let(:user) { build_stubbed(:user, created_at: Time.zone.parse("2024-01-15")) }
+
+    it "formats date in long format" do
+      expect(formatted_date).to eq("January 15, 2024")
+    end
+  end
+end
+```
+
+### Testing with Helpers
+
+Access helpers via `helpers` method in tests:
+
+```ruby
+RSpec.describe PostDecorator do
+  subject(:decorator) { described_class.new(post) }
+
+  let(:post) { create(:post) }
+
+  it "generates correct path" do
+    expect(decorator.edit_link).to include(helpers.edit_post_path(post))
+  end
+end
+```
+
+### Testing HTML Output with Capybara
+
+```ruby
+RSpec.describe StatusDecorator do
+  subject(:decorator) { described_class.new(order) }
+
+  describe "#status_badge" do
+    subject(:badge) { decorator.status_badge }
+
+    context "when completed" do
+      let(:order) { build_stubbed(:order, :completed) }
+
+      it "renders success badge" do
+        markup = Capybara.string(badge)
+        expect(markup).to have_css("span.badge-success", text: "Completed")
+      end
+    end
+  end
+end
+```
+
+## Common Anti-Patterns
+
+### Fat Decorator
+
+Split large decorators into context-specific ones:
+
+```ruby
+# Instead of one 500-line UserDecorator, use:
+class Users::ProfileDecorator < ApplicationDecorator
+  # Profile-related presentation
+end
+
+class Users::AdminDecorator < ApplicationDecorator
+  # Admin panel presentation
+end
+```
+
+### N+1 Queries
+
+```ruby
+# BAD - triggers N+1
+@posts = Post.all.decorate
+# In decorator: author.name triggers query per post
+
+# GOOD - eager load first
+@posts = Post.includes(:author).all.decorate
+```
+
+### Decorating Too Early
+
+```ruby
+# BAD - decorated objects in business logic
+def publish(decorated_post)
+  decorated_post.update(published: true)
+end
+
+# GOOD - use models for business logic
+def publish(post)
+  post.update(published: true)
+end
+# Decorate only in controller before render
+```
+
+### Using Decorators in Models
+
+```ruby
+# BAD - model references decorator
+class Post < ApplicationRecord
+  def display_title
+    PostDecorator.new(self).formatted_title
+  end
+end
+
+# GOOD - keep models unaware of decorators
+```
+
+## Quick Reference
+
+| Method | Purpose |
+|--------|---------|
+| `object` / `model` | Access wrapped object |
+| `h` / `helpers` | Access view helpers |
+| `context` | Access passed context hash |
+| `delegate_all` | Delegate all methods to object |
+| `decorates_association` | Auto-decorate associations |
+| `decorate` | Decorate single object |
+| `decorate_collection` | Decorate collection |
+
+## Additional Resources
+
+### Reference Files
+
+For detailed patterns and examples:
+- **`references/patterns.md`** - Advanced patterns, association decoration, context handling
+- **`references/testing.md`** - Comprehensive RSpec testing guide
+- **`references/anti-patterns.md`** - Detailed anti-patterns with solutions
+
+### Example Files
+
+Working examples in `examples/`:
+- **`examples/application_decorator.rb`** - Base decorator template
+- **`examples/model_decorator.rb`** - Full decorator example
+- **`examples/decorator_spec.rb`** - Complete spec template

data/skills/draper-decorators/examples/application_decorator.rb

@@ -0,0 +1,61 @@
+# app/decorators/application_decorator.rb
+#
+# Base decorator with shared presentation methods.
+# All decorators should inherit from this class.
+#
+class ApplicationDecorator < Draper::Decorator
+  # Common date formatting
+  #
+  # @param date [Time, Date, nil] the date to format
+  # @param format [Symbol] the I18n format key
+  # @return [String] formatted date or "N/A"
+  def formatted_date(date = created_at, format: :long)
+    return "N/A" if date.blank?
+
+    h.l(date, format:)
+  end
+
+  # Relative time (e.g., "2 hours ago")
+  #
+  # @param time [Time] the time to format
+  # @return [String] relative time string
+  def time_ago(time = created_at)
+    "#{h.time_ago_in_words(time)} ago"
+  end
+
+  # Currency formatting
+  #
+  # @param amount [Numeric, nil] the amount to format
+  # @return [String] formatted currency
+  def formatted_currency(amount)
+    return "$0.00" if amount.blank?
+
+    h.number_to_currency(amount)
+  end
+
+  # Truncate text with word boundary
+  #
+  # @param text [String] text to truncate
+  # @param length [Integer] maximum length
+  # @return [String] truncated text
+  def truncated_text(text, length: 100)
+    h.truncate(text.to_s, length:, separator: " ")
+  end
+
+  # Safe boolean display
+  #
+  # @param value [Boolean] the boolean to display
+  # @return [String] "Yes" or "No"
+  def boolean_display(value)
+    value ? "Yes" : "No"
+  end
+
+  # Status badge helper
+  #
+  # @param text [String] badge text
+  # @param type [Symbol] badge type (:success, :warning, :danger, :info, :secondary)
+  # @return [String] HTML span element
+  def badge(text, type: :secondary)
+    h.content_tag(:span, text, class: "badge badge-#{type}")
+  end
+end

data/skills/draper-decorators/examples/decorator_spec.rb

@@ -0,0 +1,253 @@
+# spec/decorators/post_decorator_spec.rb
+#
+# Complete decorator spec template demonstrating best practices.
+#
+require "rails_helper"
+
+RSpec.describe PostDecorator do
+  subject(:decorator) { described_class.new(post, context:) }
+
+  let(:post) { build_stubbed(:post, attributes) }
+  let(:attributes) { {} }
+  let(:context) { {} }
+
+  describe "#formatted_title" do
+    subject(:formatted_title) { decorator.formatted_title }
+
+    let(:attributes) { { title: "my post title" } }
+
+    it "titleizes the title" do
+      expect(formatted_title).to eq("My Post Title")
+    end
+
+    context "with max_length" do
+      subject(:formatted_title) { decorator.formatted_title(max_length: 10) }
+
+      let(:attributes) { { title: "a very long post title" } }
+
+      it "truncates to specified length" do
+        expect(formatted_title.length).to be <= 13 # includes "..."
+      end
+    end
+  end
+
+  describe "#status_badge" do
+    subject(:badge) { decorator.status_badge }
+
+    context "when published" do
+      let(:post) { build_stubbed(:post, :published) }
+
+      it "renders success badge" do
+        markup = Capybara.string(badge)
+
+        expect(markup).to have_css("span.badge.badge-success", text: "Published")
+      end
+    end
+
+    context "when draft" do
+      let(:post) { build_stubbed(:post, :draft) }
+
+      it "renders warning badge" do
+        markup = Capybara.string(badge)
+
+        expect(markup).to have_css("span.badge.badge-warning", text: "Draft")
+      end
+    end
+  end
+
+  describe "#publication_date" do
+    subject(:publication_date) { decorator.publication_date }
+
+    context "when published" do
+      let(:attributes) { { published_at: Time.zone.parse("2024-03-15") } }
+
+      it "formats the date" do
+        expect(publication_date).to eq("March 15, 2024")
+      end
+    end
+
+    context "when not published" do
+      let(:attributes) { { published_at: nil } }
+
+      it "returns not published message" do
+        expect(publication_date).to eq("Not published")
+      end
+    end
+  end
+
+  describe "#reading_time" do
+    subject(:reading_time) { decorator.reading_time }
+
+    let(:attributes) { { body: "word " * 400 } }
+
+    it "calculates reading time" do
+      expect(reading_time).to eq("2 min read")
+    end
+  end
+
+  describe "#excerpt" do
+    subject(:excerpt) { decorator.excerpt }
+
+    let(:attributes) { { body: "a " * 150 } }
+
+    it "truncates body" do
+      expect(excerpt.length).to be <= 203 # 200 + "..."
+    end
+
+    it "truncates at word boundary" do
+      expect(excerpt).not_to end_with("a...")
+    end
+  end
+
+  describe "#edit_link" do
+    subject(:link) { decorator.edit_link }
+
+    context "without current_user" do
+      let(:context) { {} }
+
+      it "returns nil" do
+        expect(link).to be_nil
+      end
+    end
+
+    context "with user who cannot edit" do
+      let(:context) { { current_user: build_stubbed(:user) } }
+
+      before do
+        allow(context[:current_user]).to receive(:can?).with(:edit, post).and_return(false)
+      end
+
+      it "returns nil" do
+        expect(link).to be_nil
+      end
+    end
+
+    context "with user who can edit" do
+      let(:post) { create(:post) }
+      let(:context) { { current_user: build_stubbed(:user) } }
+
+      before do
+        allow(context[:current_user]).to receive(:can?).with(:edit, post).and_return(true)
+      end
+
+      it "renders edit link" do
+        markup = Capybara.string(link)
+
+        expect(markup).to have_link("Edit", href: "/posts/#{post.id}/edit")
+      end
+
+      it "has button classes" do
+        markup = Capybara.string(link)
+
+        expect(markup).to have_css("a.btn.btn-sm.btn-secondary")
+      end
+    end
+  end
+
+  describe "#delete_link" do
+    subject(:link) { decorator.delete_link }
+
+    context "with user who can delete" do
+      let(:post) { create(:post) }
+      let(:context) { { current_user: build_stubbed(:user) } }
+
+      before do
+        allow(context[:current_user]).to receive(:can?).with(:delete, post).and_return(true)
+      end
+
+      it "renders delete link with confirmation" do
+        markup = Capybara.string(link)
+
+        expect(markup).to have_css("a[data-confirm='Are you sure?']", text: "Delete")
+      end
+    end
+  end
+
+  describe "#action_buttons" do
+    subject(:buttons) { decorator.action_buttons }
+
+    context "with no permissions" do
+      let(:context) { {} }
+
+      it "returns nil" do
+        expect(buttons).to be_nil
+      end
+    end
+
+    context "with edit permission" do
+      let(:post) { create(:post) }
+      let(:context) { { current_user: build_stubbed(:user) } }
+
+      before do
+        allow(context[:current_user]).to receive(:can?).with(:edit, post).and_return(true)
+        allow(context[:current_user]).to receive(:can?).with(:delete, post).and_return(false)
+      end
+
+      it "renders button group" do
+        markup = Capybara.string(buttons)
+
+        expect(markup).to have_css("div.btn-group")
+        expect(markup).to have_link("Edit")
+        expect(markup).not_to have_link("Delete")
+      end
+    end
+  end
+
+  describe "associations" do
+    describe "#author" do
+      subject(:author) { decorator.author }
+
+      let(:post) { create(:post) }
+
+      it "returns decorated author" do
+        expect(author).to be_decorated_with(AuthorDecorator)
+      end
+    end
+
+    describe "#comments" do
+      subject(:comments) { decorator.comments }
+
+      let(:post) { create(:post) }
+
+      before { create_list(:comment, 3, post:) }
+
+      it "returns decorated comments" do
+        expect(comments).to all(be_decorated_with(CommentDecorator))
+      end
+
+      it "includes all comments" do
+        expect(comments.size).to eq(3)
+      end
+    end
+  end
+
+  describe "#author_info" do
+    subject(:info) { decorator.author_info }
+
+    let(:post) { create(:post) }
+
+    it "renders author info block" do
+      markup = Capybara.string(info)
+
+      expect(markup).to have_css("div.author-info")
+      expect(markup).to have_css("span.author-name")
+      expect(markup).to have_css("span.post-date")
+    end
+  end
+
+  describe "#meta_info" do
+    subject(:meta) { decorator.meta_info }
+
+    let(:post) { create(:post, :with_category) }
+
+    before { create_list(:comment, 2, post:) }
+
+    it "renders meta information" do
+      markup = Capybara.string(meta)
+
+      expect(markup).to have_css("div.post-meta")
+      expect(markup).to have_link(post.category.name)
+      expect(markup.text).to include("2 comments")
+    end
+  end
+end