Add task assignments and update documentation

Author: despo

.rubocop.yml

@@ -8,3 +8,7 @@ inherit_gem: { rubocop-rails-omakase: rubocop.yml }
 # # Use `[a, [b, c]]` not `[ a, [ b, c ] ]`
 # Layout/SpaceInsideArrayLiteralBrackets:
 #   Enabled: false
+#
+AllCops:
+  TargetRubyVersion: 3.1
+

CHANGELOG.md

@@ -7,6 +7,9 @@
 - Introduced complete! method in Todoro::Task to set completed_at timestamp and mark tasks as completed.
 - Added Todoro::TaskStep model, allowing tasks to have multiple subtasks.
 - Integrated Turbo to enable dynamic subtask creation and completion without full-page reloads.
+- Introduced `taskable_assignee`, allowing models to register as assignable entities.
+- Tasks now support dynamic polymorphic assignments to multiple assignees (e.g., `Employee`, `Role`).
+- Automatically generates `has_many` associations in `Todoro::Task` for each registered `taskable_assignee`.
 
 ### 0.1.5 - 2025-02-16
 

README.md

@@ -1,71 +1,121 @@
 # Todoro
 
-A lightweight Rails engine that lets any model manage task lists and tasks with a simple, flexible API.
+A lightweight Rails engine that enables any model to manage task lists and tasks with a simple, flexible API.
 
 ![Totoro](totoro.png)
 
 ## Installation
 
-Add to your Gemfile:
+Add `todoro` to your Gemfile:
 
 ```ruby
-gem "todoro"
+gem 'todoro'
 ```
 
-And then execute:
+Then execute:
 
 ```sh
 $ bundle install
 ```
 
-Or install it yourself as:
+Or install it manually:
 
 ```sh
 $ gem install todoro
 ```
 
 ## Usage
 
+### Setup
+
 Generate the required migrations:
 
 ```sh
 $ rails generate todoro:install
 $ rails db:migrate
 ```
 
-Include `acts_as_taskable` in the model(s) that can have tasks:
+### Making Models Taskable
+
+Include `acts_as_taskable` in any model that should manage tasks:
 
 ```ruby
 class Project < ApplicationRecord
   acts_as_taskable
 end
 ```
 
-Now, a `Project` can have task lists and tasks:
+This allows a `Project` to have task lists and tasks:
+
+```ruby
+project = Project.create(name: 'Website Redesign')
+task_list = project.create_task_list('Development Tasks')
+task = project.add_task_to_list(task_list, 'Build homepage', 'Implement UI components')
+
+puts project.tasks # Lists all tasks across its task lists
+```
+
+### Assigning Tasks to Entities
+
+To assign tasks to various entities (e.g., `User`, `Role`), ensure these models are assignable.
+
+#### 1. Declare Assignable Models
+
+In each model that should be assignable, simply call `taskable_assignee`:
 
 ```ruby
-project = Project.create(name: "Website Redesign")
-task_list = project.create_task_list("Development Tasks")
-task = project.add_task_to_list(task_list, "Build homepage", "Implement UI components")
+class User < ApplicationRecord
+  taskable_assignee
+end
+
+class Role < ApplicationRecord
+  taskable_assignee
+end
+```
+
+#### 2. Assign Tasks
+
+With models configured, assign tasks as follows:
+
+```ruby
+user = User.create(name: 'Jane Doe')
+role = Role.create(name: 'Developer')
+
+# Assign task to assignable models
+task.assign_to(user)
+task.assign_to(role)
+
+# Retrieve specific assignees
+task.employees # => [#<User id: 1, name: "Jane Doe">]
+task.roles     # => [#<Role id: 1, name: "Developer">]
+```
+
+### Managing Task Steps
+
+Tasks can be broken down into multiple steps, allowing for a structured workflow.
+
+```ruby
+# Add task steps
+task.task_steps.create(title: 'Design UI mockups')
+task.task_steps.create(title: 'Write backend API')
 
-puts project.tasks # Lists all tasks in all its task lists
 ```
 
 ## Automatic Route Generation
 
-Todoro automatically generates routes for any model that includes `acts_as_taskable`. For example, if `Project` includes `acts_as_taskable`, the following routes are created:
+Todoro automatically generates routes for any model that includes `acts_as_taskable`. For example, if `Project` includes `acts_as_taskable`, this is part of the generated routes:
 
-```sh
-GET    /projects/:project_id/task_lists(.:format)
-POST   /projects/:project_id/task_lists(.:format)
-GET    /projects/:project_id/task_lists/:id(.:format)
-PATCH  /projects/:project_id/task_lists/:id(.:format)
-DELETE /projects/:project_id/task_lists/:id(.:format)
-GET    /projects/:project_id/task_lists/:task_list_id/tasks(.:format)
-POST   /projects/:project_id/task_lists/:task_list_id/tasks(.:format)
+```
+/projects/:project_id/task_lists
+/projects/:project_id/task_lists/:id
+/projects/:project_id/task_lists/:id/tasks
+/projects/:project_id/task_lists/:id/tasks/:id
+/projects/:project_id/task_lists/:task_list_id/tasks/:id/complete
+/projects/:project_id/task_lists/:task_list_id/tasks/:task_id/step
+/projects/:project_id/task_lists/:task_list_id/tasks/:task_id/step/:id/complete
 ```
 
-These routes are automatically configured, so no additional setup is needed.
+These routes allow for managing task lists and tasks within the context of the `Project` model.
 
 ## Mounting the Engine
 
@@ -74,7 +124,7 @@ To access Todoro's routes, mount the engine in your application's routes file:
 ```ruby
 # config/routes.rb
 Rails.application.routes.draw do
-  mount Todoro::Engine, at: "/"
+  mount Todoro::Engine, at: '/'
   # Other routes...
 end
 ```

app/models/todoro/task.rb

@@ -5,8 +5,6 @@ class Task < ApplicationRecord
     has_many :task_steps, class_name: "Todoro::TaskStep", dependent: :destroy
 
     has_many :task_assignments, dependent: :destroy
-    has_many :assignees, through: :task_assignments, source: :assignee
-
 
     validates :title, presence: true
     validates :status, presence: true, inclusion: { in: %w[pending completed] }

lib/todoro.rb

@@ -1,6 +1,7 @@
 require "todoro/version"
 require "todoro/engine"
 require "todoro/taskable"
+require "todoro/taskable_assignee"
 
 module Todoro
   mattr_accessor :assignable_models

lib/todoro/taskable_assignee.rb

@@ -10,7 +10,15 @@ module TaskableAssignee
     class_methods do
       def taskable_assignee
         Todoro.assignable_models << self.name unless Todoro.assignable_models.include?(self.name)
+
+        Todoro::Task.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            has_many :#{self.name.underscore.pluralize}, through: :task_assignments, source: :assignee, source_type: "#{self.name}"
+        RUBY
       end
     end
   end
 end
+
+ActiveSupport.on_load(:active_record) do
+  extend Todoro::TaskableAssignee::ClassMethods
+end

spec/todoapp/app/models/employee.rb

@@ -0,0 +1,3 @@
+class Employee < ApplicationRecord
+  taskable_assignee
+end

spec/todoapp/app/models/user.rb

@@ -0,0 +1,3 @@
+class User < ApplicationRecord
+  taskable_assignee
+end

spec/todoapp/db/migrate/20250217155710_create_task_assignments.todoro.rb

@@ -0,0 +1,11 @@
+# This migration comes from todoro (originally 20250217155125)
+class CreateTaskAssignments < ActiveRecord::Migration[7.2]
+  def change
+    create_table :todoro_task_assignments do |t|
+      t.references :task, null: false, foreign_key: { to_table: :todoro_tasks }
+      t.references :assignee, polymorphic: true, null: false
+
+      t.timestamps
+    end
+  end
+end

spec/todoapp/db/migrate/20250217155740_create_users.rb

@@ -0,0 +1,9 @@
+class CreateUsers < ActiveRecord::Migration[7.2]
+  def change
+    create_table :users do |t|
+      t.string :name
+
+      t.timestamps
+    end
+  end
+end