[7926] CSV reference docs (#4894)

* Add rake task to generate trainee bulk upload docs

This is a one-off rake task to convert a CSV file (that was exported
from a table in a Word document) into a YAML file that can be used as
the data source for a Trainee bulk upload CSV reference document.

* WIP

* Render content on /csv-docs page

Still needs some manual formatting of the content

* Fix layout of CSV fields

One CSS rule is needed to correct the styling of p paragraph elements
within a summary component.

* Manual tweaks to correct formatting of CSV docs

* Fix issue with internal links

* Only process certain fields as markdown

* Add component specs

* Add links to HESA reference docs

* Appease Rubocop and friends

* Add link to CSV docs from main trainee upload page

* Remove one-off rake task to 'import' CSV docs

This little script has done it's work

* Apply suggestions from code review

Various formatting changes following code review

Co-authored-by: Serafeim Maroulis <[email protected]>

* Add steps to feature spec for CSV docs

And other review feedback

* Corrections to CSV reference

A few things went awry after the merging in a few review suggestions.

* Appease Rubocop

* Quote HTML attribute values

Co-authored-by: Tom Trentham <[email protected]>

* Add missing email hyperlink

Co-authored-by: Tom Trentham <[email protected]>

* Corrections to copy for CSV reference

Descriptions for lead partner URN and employing school URN

* Revert the change to lead partner column name

This column heading was changed from _Lead Partner URN_ to _Lead Partner URN\_UKPRN_
but we will need to make several other changes to facilitate this so
the requirement to support lead partner UKPRNs will be handled by a
separate ticket - https://trello.com/c/2ETvpR3K/157-support-input-of-lead-partner-ukprn-as-well-as-urn

* Revert change to summary card as it causes double quotation

---------

Co-authored-by: Serafeim Maroulis <[email protected]>
Co-authored-by: Tom Trentham <[email protected]>

app/assets/stylesheets/application.scss

@@ -26,6 +26,7 @@ $mobile-big-end: 501px;
 @import "components/all";
 @import "utilities";
 @import "api-docs";
+@import "csv-docs";
 
 .govuk-cookie-banner__hide {
   display: none;

app/assets/stylesheets/csv-docs.scss

@@ -0,0 +1,3 @@
+.csv-field-list dd > p {
+  margin-top: 0;
+}

app/components/csv_field_summary/view.html.erb

@@ -0,0 +1,6 @@
+<%= render SummaryCard::View.new(
+  title: summary_title,
+  rows: rows,
+  editable: false,
+  id: "summary-card-#{summary_id}",
+) %>

app/components/csv_field_summary/view.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module CsvFieldSummary
+  class View < ViewComponent::Base
+    include SummaryHelper
+
+    attr_reader :attributes
+
+    MARKDOWN_ATTRIBUTES = %w[description format example].freeze
+
+    def initialize(attributes)
+      @attributes = attributes
+    end
+
+    def summary_title
+      @attributes["field_name"]
+    end
+
+    def summary_id
+      @attributes["technical"].parameterize
+    end
+
+    def rows
+      @attributes.map do |key, value|
+        {
+          key: t("components.csv_field_summary.view.#{key}"),
+          value: convert_value_to_html(key, value),
+        }
+      end
+    end
+
+  private
+
+    def markdown_render
+      @markdown_render ||= Redcarpet::Render::HTML.new(
+        link_attributes: { class: "govuk-link" },
+        paragraph_attributes: { class: "govuk-body" },
+      )
+    end
+
+    def convert_value_to_html(key, value)
+      if MARKDOWN_ATTRIBUTES.include?(key)
+        value.is_a?(String) ? Redcarpet::Markdown.new(markdown_render).render(value).html_safe : ""
+      else
+        value
+      end
+    end
+  end
+end

app/components/csv_fields/view.html.erb

@@ -0,0 +1,11 @@
+<ul class="govuk-list">
+  <% fields.each do |attributes| %>
+    <li><a href="#summary-card-<%= attributes["technical"].parameterize %>"><%= attributes["field_name"] %></a></li>
+  <% end %>
+</ul>
+
+<div class="csv-field-list">
+  <% fields.each do |attributes| %>
+    <%= render CsvFieldSummary::View.new(attributes) %>
+  <% end %>
+</div>

app/components/csv_fields/view.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CsvFields
+  class View < ViewComponent::Base
+    include SummaryHelper
+
+    FIELD_DEFINITION_PATH = Rails.root.join("app/views/bulk_update/add_trainees/reference_docs/fields.yaml")
+
+    attr_reader :fields
+
+    def initialize
+      @fields = YAML.load_file(FIELD_DEFINITION_PATH)
+    end
+  end
+end

app/components/summary_card/view.html.erb

@@ -1,4 +1,4 @@
-<section class="app-summary-card govuk-!-margin-bottom-6">
+<section class="app-summary-card govuk-!-margin-bottom-6" <%= "id=#{id}" if id.present? %>>
   <header class="app-summary-card__header">
     <h<%= heading_level %> class="app-summary-card__title">
       <%= title %>

app/components/summary_card/view.rb

@@ -3,12 +3,13 @@
 class SummaryCard::View < ViewComponent::Base
   renders_one :header_actions
 
-  def initialize(title:, heading_level: 2, rows:, id_suffix: nil, editable: true)
+  def initialize(title:, heading_level: 2, rows:, id_suffix: nil, editable: true, id: nil)
     @title = title
     @heading_level = heading_level
     @rows = rows
     @editable = editable
     @id_suffix = id_suffix
+    @id = id
   end
 
   def summary_rows
@@ -17,7 +18,7 @@ def summary_rows
 
 private
 
-  attr_accessor :title, :heading_level, :id_suffix, :editable
+  attr_accessor :title, :heading_level, :id_suffix, :editable, :id
 
   def row_title(key)
     return key.parameterize if id_suffix.nil?

app/controllers/csv_docs/base_controller.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CsvDocs
+  class BaseController < ::ApplicationController
+    skip_before_action :authenticate
+    before_action { require_feature_flag(:bulk_add_trainees) }
+  end
+end

app/controllers/csv_docs/pages_controller.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CsvDocs
+  class PagesController < CsvDocs::BaseController
+    DEFAULT_PAGE = "add_trainees"
+
+    def show
+      render(DEFAULT_PAGE)
+    end
+  end
+end