Merge pull request #4326 from alphagov/update-component-guide-order

Make it easier to find application level components in component guides

.github/workflows/visual-regression-tests.yml

@@ -53,3 +53,4 @@ jobs:
       - run: yarn run percy exec -- bundle exec rspec --tag visual_regression
         env:
           PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}
+          MAIN_COMPONENT_GUIDE: true

app/controllers/govuk_publishing_components/component_guide_controller.rb

@@ -9,7 +9,8 @@ def index
       @component_gem_path = Gem.loaded_specs["govuk_publishing_components"].full_gem_path
       @component_docs = component_docs.all
       @gem_component_docs = gem_component_docs.all
-      @components_in_use_docs = components_in_use_docs.used_in_this_app
+      @used_components = used_components_names.get_component_docs
+      @unused_components = unused_components_names.get_component_docs
       @components_in_use_sass = components_in_use_sass
       @components_in_use_js = components_in_use_js
     end
@@ -47,7 +48,7 @@ def components_in_use_sass
       additional_files = "@import 'govuk_publishing_components/govuk_frontend_support';\n"
       additional_files << "@import 'govuk_publishing_components/component_support';\n"
 
-      components = find_all_partials_in(components_in_use)
+      components = find_all_partials_in(get_used_component_names)
 
       components.map { |component|
         "@import 'govuk_publishing_components/components/#{component.gsub('_', '-')}';" if component_has_sass_file(component.gsub("_", "-"))
@@ -57,7 +58,7 @@ def components_in_use_sass
     def components_in_use_js
       additional_files = "//= require govuk_publishing_components/lib\n"
 
-      components = find_all_partials_in(components_in_use)
+      components = find_all_partials_in(get_used_component_names)
 
       components.map { |component|
         "//= require govuk_publishing_components/components/#{component.gsub('_', '-')}" if component_has_js_file(component.gsub("_", "-"))
@@ -74,11 +75,15 @@ def gem_component_docs
       @gem_component_docs ||= ComponentDocs.new(gem_components: true)
     end
 
-    def components_in_use_docs
-      @components_in_use_docs ||= ComponentDocs.new(gem_components: true, limit_to: components_in_use)
+    def used_components_names
+      @used_components_names ||= ComponentDocs.new(gem_components: true, limit_to: get_used_component_names)
     end
 
-    def components_in_use
+    def unused_components_names
+      @unused_components_names ||= ComponentDocs.new(gem_components: true, limit_to: get_unused_component_names)
+    end
+
+    def get_used_component_names
       matches = []
 
       files = Dir["#{@application_path}/app/views/**/*.erb"]
@@ -93,6 +98,11 @@ def components_in_use
       matches.flatten.uniq.map(&:to_s).sort
     end
 
+    def get_unused_component_names
+      all_components = ComponentDocs.new(gem_components: true).all.map(&:id)
+      all_components - get_used_component_names
+    end
+
     def find_all_partials_in(templates)
       components = [templates]
 

app/models/govuk_publishing_components/component_docs.rb

@@ -12,11 +12,11 @@ def get(id)
     end
 
     def all
-      fetch_component_docs.map { |component| build(component) }.sort_by(&:name)
+      fetch_component_doc_files.map { |component| build(component) }.sort_by(&:name)
     end
 
-    def used_in_this_app
-      fetch_component_docs.map { |component| build(component) if component_in_use(component[:id]) }.compact.sort_by(&:name)
+    def get_component_docs
+      fetch_component_doc_files.map { |component| build(component) if component_in_use?(component[:id]) }.compact.sort_by(&:name)
     end
 
   private
@@ -25,13 +25,13 @@ def build(component)
       ComponentDoc.new(component)
     end
 
-    def fetch_component_docs
+    def fetch_component_doc_files
       doc_files = Rails.root.join(@documentation_directory, "*.yml")
       Dir[doc_files].sort.map { |file| parse_documentation(file) }
     end
 
-    def component_in_use(component)
-      true if @limit_to.include?(component)
+    def component_in_use?(component)
+      @limit_to.include?(component)
     end
 
     def fetch_component_doc(id)

app/views/govuk_publishing_components/component_guide/index.html.erb

@@ -15,8 +15,20 @@
   } %>
 </form>
 
-<% unless ENV["MAIN_COMPONENT_GUIDE"] %>
-  <h2 class="component-doc-h2">Gem components used by this app (<%= @components_in_use_docs.length %>)</h2>
+<% if !ENV["MAIN_COMPONENT_GUIDE"] %>
+  <h2 class="component-doc-h2">Components in this application (<%= @component_docs.length %>)</h2>
+  <ul class="component-list" id="list-components-in-this-application">
+    <% @component_docs.each do |component_doc| %>
+      <li>
+        <%= link_to component_doc.name, component_doc_path(component_doc.id), class: "govuk-link" %>
+        <p>
+          <%= component_doc.description %>
+        </p>
+      </li>
+    <% end %>
+  </ul>
+
+  <h2 class="component-doc-h2">Gem components used by this app (<%= @used_components.length %>)</h2>
 
   <%= render "govuk_publishing_components/components/details", {
     title: "Suggested imports for this application"
@@ -41,7 +53,7 @@
 </pre>
 
   <ul class="component-list">
-    <% @components_in_use_docs.each do |component_doc| %>
+    <% @used_components.each do |component_doc| %>
       <li>
         <%= link_to component_doc.name, component_doc_path(component_doc.id), class: "govuk-link" %>
         <p>
@@ -50,12 +62,10 @@
       </li>
     <% end %>
   </ul>
-<% end %>
 
-<% unless ENV["MAIN_COMPONENT_GUIDE"] %>
-  <h2 class="component-doc-h2">Components in this application (<%= @component_docs.length %>)</h2>
-  <ul class="component-list" id="list-components-in-this-application">
-    <% @component_docs.each do |component_doc| %>
+  <h2 class="component-doc-h2">Gem components not used by this app (<%= @unused_components.length %>)</h2>
+  <ul class="component-list">
+    <% @unused_components.each do |component_doc| %>
       <li>
         <%= link_to component_doc.name, component_doc_path(component_doc.id), class: "govuk-link" %>
         <p>
@@ -65,20 +75,19 @@
     <% end %>
   </ul>
 
-  <h2 class="component-doc-h2">All gem components (<%= @gem_component_docs.length %>)</h2>
+<% else %>
+  <ul class="component-list" id="list-all-components-in-the-gem">
+    <% @gem_component_docs.each do |component_doc| %>
+      <li>
+        <%= link_to component_doc.name, component_doc_path(component_doc.id), class: "govuk-link" %>
+        <p>
+          <%= component_doc.description %>
+        </p>
+      </li>
+    <% end %>
+  </ul>
 <% end %>
 
-<ul class="component-list" id="list-all-components-in-the-gem">
-  <% @gem_component_docs.each do |component_doc| %>
-    <li>
-      <%= link_to component_doc.name, component_doc_path(component_doc.id), class: "govuk-link" %>
-      <p>
-        <%= component_doc.description %>
-      </p>
-    </li>
-  <% end %>
-</ul>
-
 <div class="component-markdown">
   <p class="govuk-body">If you cannot find a suitable component consider extending an existing component or <a href="https://github.com/alphagov/govuk_publishing_components/blob/main/docs/generate-a-new-component.md">creating a new one</a>.</p>
 </div>