feature: description for resource

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,23 @@
+# Description
+<!-- Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change. -->
+
+Fixes # (issue)
+
+# Checklist:
+
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the [documentation](https://docs.avohq.io)
+- [ ] My changes generate no new warnings
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] Covered by automated tests.
+
+
+## Manual review steps
+
+Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration.
+
+1. Step 1
+1. Step 2
+
+Manual reviewer: please leave a comment with output from the test if that's the case.

app/components/avo/panel_component.html.erb

@@ -9,6 +9,9 @@
       <div class="text-2xl tracking-normal font-bold text-gray-800 truncate" data-target="title">
         <%= @title %>
       </div>
+      <div class="text-sm tracking-normal text-gray-600" data-target="description">
+        <%== description %>
+      </div>
     </div>
 
     <div>

app/components/avo/panel_component.rb

@@ -6,8 +6,9 @@ class Avo::PanelComponent < ViewComponent::Base
   renders_one :bare_content
   renders_one :footer
 
-  def initialize(title: nil, body_classes: nil, data: {}, display_breadcrumbs: false, index: nil)
+  def initialize(title: nil, description: nil, body_classes: nil, data: {}, display_breadcrumbs: false, index: nil)
     @title = title
+    @description = description
     @body_classes = body_classes
     @data = data
     @display_breadcrumbs = display_breadcrumbs
@@ -25,4 +26,10 @@ def data_attributes
   def display_breadcrumbs?
     @display_breadcrumbs
   end
+
+  def description
+    return @description if @description.present?
+
+    '&nbsp;'
+  end
 end

app/components/avo/views/resource_edit_component.html.erb

@@ -3,7 +3,7 @@
     <%= form_with model: @resource.model, scope: @resource.form_scope, url: helpers.resource_path(model: @resource.model, resource: @resource), method: :put, multipart: true do |form| %>
       <%= hidden_field_tag :referrer, back_path if params[:via_resource_class] %>
 
-      <%= render Avo::PanelComponent.new(title: resource_panel[:name], display_breadcrumbs: true) do |c| %>
+      <%= render Avo::PanelComponent.new(title: resource_panel[:name], description: @resource.resource_description, display_breadcrumbs: true) do |c| %>
         <% c.tools do %>
           <div class="flex justify-end space-x-2">
             <%= a_link back_path do %>

app/components/avo/views/resource_index_component.html.erb

@@ -1,5 +1,5 @@
 <div>
-  <%= render Avo::PanelComponent.new(title: title, body_classes: 'py-4', data: { component: 'resources-index' }, display_breadcrumbs: @reflection.blank?) do |c| %>
+  <%= render Avo::PanelComponent.new(title: title, description: @resource.resource_description, body_classes: 'py-4', data: { component: 'resources-index' }, display_breadcrumbs: @reflection.blank?) do |c| %>
     <% c.tools do %>
       <%= render 'actions' if @actions.present? %>
 

app/components/avo/views/resource_new_component.html.erb

@@ -1,7 +1,7 @@
 <div>
   <% @resource.panels.each do |resource_panel| %>
     <%= form_with model: @resource.model, url: helpers.resources_path(resource: @resource, via_relation_class: params[:via_relation_class], via_relation: params[:via_relation], via_resource_id: params[:via_resource_id]), local: true, multipart: true do |form| %>
-      <%= render Avo::PanelComponent.new(title: resource_panel[:name], display_breadcrumbs: true) do |c| %>
+      <%= render Avo::PanelComponent.new(title: resource_panel[:name], description: @resource.resource_description, display_breadcrumbs: true) do |c| %>
         <% c.tools do %>
           <div class="flex justify-end space-x-2">
             <%= a_link back_path do %>

app/components/avo/views/resource_show_component.html.erb

@@ -3,7 +3,7 @@
   data-selected-resources='["<%= @resource.model.id %>"]'
 >
   <% @resource.panels.each_with_index do |resource_panel, index| %>
-    <%= render Avo::PanelComponent.new(title: title, display_breadcrumbs: @reflection.blank?, index: index) do |c| %>
+    <%= render Avo::PanelComponent.new(title: title, description: @resource.resource_description, display_breadcrumbs: @reflection.blank?, index: index) do |c| %>
       <% c.tools do %>
         <% if resource_panel[:name] == @resource.default_panel_name %>
           <%= render 'actions' %>

lib/avo/base_resource.rb

@@ -19,6 +19,7 @@ class BaseResource
 
     class_attribute :id, default: :id
     class_attribute :title, default: :id
+    class_attribute :description, default: :id
     class_attribute :search_query, default: nil
     class_attribute :search_query_help, default: ''
     class_attribute :includes, default: []
@@ -230,6 +231,16 @@ def model_title
       name
     end
 
+    def resource_description
+      return instance_exec(&self.class.description) if self.class.description.respond_to? :call
+
+      # Show the description only on the resource index view.
+      # If the user wants to conditionally it on all pages, they should use a block.
+      if view == :index
+        return self.class.description if self.class.description.is_a? String
+      end
+    end
+
     def translation_key
       return "avo.resource_translations.#{class_name_without_resource.underscore}" if self.class.translation_enabled
 

spec/dummy/app/avo/resources/person_resource.rb

@@ -1,5 +1,6 @@
 class PersonResource < Avo::BaseResource
   self.title = :name
+  self.description = 'People on the app'
   self.includes = []
 
   # self.search_query = ->(params:) do

spec/dummy/app/avo/resources/user_resource.rb

@@ -1,5 +1,8 @@
 class UserResource < Avo::BaseResource
   self.title = :name
+  self.description = -> () {
+    "These are the users of the app. view: #{view}"
+  }
   self.translation_key = "avo.resource_translations.user"
   self.search_query = ->(params:) do
     scope.ransack(id_eq: params[:q], first_name_cont: params[:q], last_name_cont: params[:q], m: "or").result(distinct: false)

spec/features/avo/resource_description_spec.rb

@@ -0,0 +1,68 @@
+require "rails_helper"
+
+RSpec.describe "resource panel description", type: :feature do
+  let(:empty) { ' ' }
+
+  subject do
+    visit url
+    find_all("[data-target='description']").first
+  end
+
+  describe 'without description' do
+    let(:url) { "/admin/resources/posts" }
+
+    context "index" do
+      it { is_expected.to have_text empty }
+    end
+  end
+
+  describe 'with description' do
+    describe 'with string' do
+      let!(:person) { create :person }
+
+      context "index" do
+        let(:url) { "/admin/resources/people" }
+        it { is_expected.to have_text 'People on the app' }
+      end
+
+      context "show" do
+        let(:url) { "/admin/resources/people/#{person.id}" }
+        it { is_expected.to have_text empty }
+      end
+
+      context "edit" do
+        let(:url) { "/admin/resources/people/#{person.id}/edit" }
+        it { is_expected.to have_text empty }
+      end
+
+      context "new" do
+        let(:url) { "/admin/resources/people/new" }
+        it { is_expected.to have_text empty }
+      end
+    end
+
+    describe 'with block' do
+      let!(:user) { create :user }
+
+      context "index" do
+        let(:url) { "/admin/resources/users" }
+        it { is_expected.to have_text 'These are the users of the app. view: index' }
+      end
+
+      context "show" do
+        let(:url) { "/admin/resources/users/#{user.id}" }
+        it { is_expected.to have_text 'These are the users of the app. view: show' }
+      end
+
+      context "edit" do
+        let(:url) { "/admin/resources/users/#{user.id}/edit" }
+        it { is_expected.to have_text 'These are the users of the app. view: edit' }
+      end
+
+      context "new" do
+        let(:url) { "/admin/resources/users/new" }
+        it { is_expected.to have_text 'These are the users of the app. view: new' }
+      end
+    end
+  end
+end