form-object-patterns_skill

Overview

This skill creates form objects for Rails 8.1 projects to handle complex form interactions with a TDD-first workflow. It provides patterns for multi-model registration forms, non-persisted search filters, wizard/multi-step flows, and contact forms that deliver email instead of persisting records. The goal is to keep controllers and models thin while centralizing validation, persistence, and presentation concerns in plain Ruby form objects.

How this skill works

You write specs first (RED), implement a form class that includes ActiveModel behavior or extends a provided ApplicationForm, and iterate until tests pass (GREEN). Form objects declare typed attributes, validations, and encapsulate persistence with a save/persist! contract or return query results for search forms. Controller and view integration use form_with model: @form and expose errors and virtual attributes just like ActiveRecord objects.

When to use it

• Building a single user flow that touches multiple models (create user + account + profile)
• Implementing search or filter UIs where results are non-persisted queries
• Designing wizard or multi-step forms that persist progress or validate per-step
• Creating contact or API-facing forms with virtual attributes and email delivery
• When you want to follow TDD: write specs for form behavior before implementation

Best practices

• Write form specs first: validate attributes, save behavior, and edge cases before coding
• Extend a shared ApplicationForm to centralize persisted? behavior, save pattern, and error handling
• Keep persistence in a private persist! method and wrap multi-model writes in a transaction
• Expose created or found records (e.g., form.user, form.account, form.results) for controller use
• Provide helper methods for view presentation (options arrays, any_filters?) and sanitize inputs for queries

Example use cases

• RegistrationForm that creates an Account and User in one transaction and exposes created records
• EventSearchForm that accepts account and params, returns scoped results and supports date/type filters
• Wizard::BaseForm with step navigation, progress percentage, and per-step validation classes
• ContactForm that validates input and delivers an email asynchronously without persisting a record