feat: add DeveloperWarningComponent for development/test environment warnings (#4383)

* feat: add DeveloperWarningComponent for development/test environment warnings

Introduced a new DeveloperWarningComponent to display warnings when fields are declared directly inside a panel without a card wrapper. This component is rendered conditionally in development and test environments, providing helpful guidance to developers. Updated panel_component to utilize this new component and added corresponding tests for its functionality.

* lint

* fix code classes

* comment docs for now

* comment docs url

Author: Paul-Bob

app/components/avo/developer_warning_component.html.erb

@@ -0,0 +1,15 @@
+<div
+  class="<%= classes %>"
+  data-tippy="tooltip"
+  title="This warning is present only on development"
+>
+  <div class="flex items-center min-h-6">
+    <%= helpers.svg icon, class: "h-6 text-orange-600 dark:text-orange-300" %>
+  </div>
+
+  <div class="flex-1 text-sm leading-5 font-semibold space-y-3">
+    <div>
+      <%= sanitize @message.to_s, sanitize_options %>
+    </div>
+  </div>
+</div>

app/components/avo/developer_warning_component.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class Avo::DeveloperWarningComponent < Avo::BaseComponent
+  include Avo::ApplicationHelper
+
+  prop :message, kind: :positional
+
+  def render?
+    Rails.env.development? || Rails.env.test?
+  end
+
+  def classes
+    "w-full flex items-start gap-3 rounded-lg border border-orange-600/40 bg-orange-50 px-4 py-3 text-orange-950 dark:border-orange-500/30 dark:bg-orange-950/30 dark:text-orange-50"
+  end
+
+  def icon
+    "tabler/filled/alert-triangle"
+  end
+
+  def sanitize_options
+    {
+      tags: %w[a code br],
+      attributes: %w[href target rel class]
+    }
+  end
+end

app/components/avo/items/panel_component.html.erb

@@ -1,5 +1,8 @@
 <%= render ui.panel(title: @item.title, description: @item.description, index: @index) do |panel| %>
   <% panel.with_body do %>
+    <% if fields_outside_card? %>
+      <%= render Avo::DeveloperWarningComponent.new(card_background_warning_message) %>
+    <% end %>
     <%= render Avo::Items::VisibleItemsComponent.new resource: @resource, item: @item, view: @view, form: @form, parent_component: @parent_component, reflection: @reflection %>
   <% end %>
 

app/components/avo/items/panel_component.rb

@@ -21,4 +21,37 @@ class Avo::Items::PanelComponent < Avo::ResourceComponent
     :can_see_the_destroy_button?,
     :can_see_the_save_button?,
     to: :@parent_component
+
+  # Warn in development/test when a developer declares fields directly inside a `panel`
+  # without wrapping them in a `card do ... end` block.
+  #
+  # This matters because cards are the thing that provides the consistent background/spacing.
+  def fields_outside_card?
+    return false unless Rails.env.development? || Rails.env.test?
+    return false unless @item.respond_to?(:visible_items)
+    return false if @item.respond_to?(:dev_warnings?) && !@item.dev_warnings?
+
+    @item.visible_items.any? do |item|
+      # Direct field under the panel will render without card background.
+      if item.is_field?
+        true
+      # Row is rendered directly by the panel too; it can contain fields rendered without card background.
+      elsif item.is_row?
+        item.visible_items.any?(&:is_field?)
+      else
+        false
+      end
+    end
+  end
+
+  def card_background_warning_message
+    # Keep the message deterministic for specs.
+    # docs_url = "https://docs.avohq.io/4.0/resource-cards.html"
+    docs_message = ""
+    # docs_message = "See the <a href=\"#{docs_url}\" target=\"_blank\" rel=\"noopener\" class=\"underline underline-offset-2\">resource cards</a> docs."
+    code_classes = "inline-flex items-center align-middle rounded bg-orange-500/10 px-1 py-px font-mono text-[0.85em] font-semibold leading-none text-orange-950 dark:bg-orange-500/15 dark:text-orange-50"
+    disable_snippet = "<code class=\"#{code_classes}\">panel dev_warnings: false do ... end</code>"
+
+    "Some fields are declared directly inside a <code class=\"#{code_classes}\">panel</code> without a <code class=\"#{code_classes}\">card do ... end</code> wrapper. Wrap them in a <code class=\"#{code_classes}\">card</code> to get the expected card background and spacing. If this is intentional and you want to avoid this warning please use #{disable_snippet}. #{docs_message}"
+  end
 end

lib/avo/resources/items/item_group.rb

@@ -23,6 +23,10 @@ def initialize(title: nil, description: nil, view: nil, **args)
     post_initialize if respond_to?(:post_initialize)
   end
 
+  def dev_warnings?
+    @args.fetch(:dev_warnings, true) != false
+  end
+
   class Builder
     include Avo::Concerns::BorrowItemsHolder
 

spec/components/avo/developer_warning_component_spec.rb

@@ -0,0 +1,29 @@
+require "rails_helper"
+
+RSpec.describe Avo::DeveloperWarningComponent, type: :component do
+  let(:message) { "Hello <a href='https://example.com'>link</a>" }
+
+  it "renders in test environment" do
+    result = render_inline(described_class.new(message))
+
+    expect(result).to have_css('[data-tippy="tooltip"]')
+    expect(result).to have_text("Hello link")
+  end
+
+  it "renders in development environment" do
+    allow(Rails).to receive(:env).and_return(ActiveSupport::StringInquirer.new("development"))
+
+    result = render_inline(described_class.new(message))
+
+    expect(result).to have_css('[data-tippy="tooltip"]')
+    expect(result).to have_text("Hello link")
+  end
+
+  it "does not render in production environment" do
+    allow(Rails).to receive(:env).and_return(ActiveSupport::StringInquirer.new("production"))
+
+    result = render_inline(described_class.new(message))
+
+    expect(result.to_html.strip).to eq("")
+  end
+end