defra_ruby_template 5.11.0 → 6.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6ae2bda97dd3c68432a6ed396a7a41e3c6573de890b8c46c139ee831c9b9dfa
-  data.tar.gz: 06006a20a4c92a0ddf63aeb8e5ef366f3dacc74a1f7cced7c09ede6f474a3491
+  metadata.gz: a44a6552ed7efbac194e9ad18ca3b89790962a374e138038b963cc3612242f14
+  data.tar.gz: c54f85edbb5c6f44c01b236ba5ff25858df2f2607573a0738a60206e33cb5427
 SHA512:
-  metadata.gz: a6849c694fb67583128983d97c8efcc885fe4a237924bfde2262928a944a5a9a1e20c37ee8272af575b6d983110b7a4eac49d0a2e129a4820774c8abc41a0bd8
-  data.tar.gz: 2ddae3a8d080d11487e1d99b4cc387900ee0705e3f4ecb87857002062d0430dd94c7df53d3cff40a23293cd3d5341a2658659b7b739e8567f2b866e5b05f5bf2
+  metadata.gz: ea3b66c2cdcfc820e4b75f502fe4fe4c5af7af10bfcd2a161bed5b7d6fa017a38f471028df605059d146dcfcfc1c58b0404e756aabbc2964d1a48bb0880b30c2
+  data.tar.gz: fd08b5eac1fb61b6b43302837ecbab4b364f7fc2eefa9b1035b33a39d7982329e48bd3d7421f1661c0e22a6f764b18ea6625e74b74671f7b659c5bbeb8c763e0

data/README.md

@@ -9,6 +9,9 @@
 
 Adds a GOV.UK-ready layout template and the [govuk_frontend assets](https://github.com/alphagov/govuk-frontend) to a Rails application.
 
+The gem's version tracks the version of govuk-frontend it vendors, so 6.4.0 of
+this gem ships govuk-frontend 6.4.0.
+
 ## Installation
 
 Add this line to the application's Gemfile:
@@ -23,12 +26,11 @@ And then execute:
 
 ## Usage
 
-The Rails application will need to have SCSS enabled (e.g. `sass-rails`).
-
-This gem includes the `defra_ruby_template` layout, and can be included  in a Rails project by adding the following to the default layout (e.g. `application.html.erb`)
-
-```
+This gem includes the `defra_ruby_template` layout, which is rendered from the
+application's own layout (e.g. `application.html.erb`). Fill the slots it
+provides with `content_for`, then render it:
 
+```erb
 <% content_for :page_title do %>
     Page title or defaults to the i18n `global_proposition_header`
 <% end %>
@@ -37,8 +39,12 @@ This gem includes the `defra_ruby_template` layout, and can be included  in a Ra
   Stylesheets, Analytics, etc.
 <% end %>
 
+<% content_for :cookies_banner do %>
+  Cookie banner
+<% end %>
+
 <% content_for :header_content do %>
- Application name and top-level links
+  Service name and navigation - see "Service navigation" below
 <% end %>
 
 <% content_for :phase_banner do %>
@@ -54,21 +60,139 @@ This gem includes the `defra_ruby_template` layout, and can be included  in a Ra
 <% end %>
 
 <%= render template: "layouts/defra_ruby_template" %>
+```
+
+## Requirements
+
+### Dart Sass
 
+**govuk-frontend 6 cannot be compiled by LibSass, and therefore not by
+`sassc-rails`.** Its stylesheets are Sass modules built on `@use`/`@forward`,
+and its support for `@import` callers depends on Dart Sass resolving sibling
+`*.import.scss` files. LibSass implements neither. It does not fail loudly
+either: it passes the `@use` rules through as literal CSS at-rules, so an
+application still boots and still serves a stylesheet - one containing no
+styles at all.
+
+An application on `sassc-rails` needs to move to a Dart Sass pipeline before
+upgrading to this version.
+
+The recommended option is [`dartsass-sprockets`][dartsass-sprockets]. It is a
+fork of `sassc-rails` that keeps the same Sprockets integration and delegates to
+Dart Sass via `sass-embedded`, so `app/assets/stylesheets/application.css.scss`
+and the `image-url`/`font-url` helpers keep working and the change is confined
+to the Gemfile:
+
+```ruby
+# gem "sassc-rails"
+gem "dartsass-sprockets"
+```
+
+`dartsass-rails` is the other option. It compiles outside Sprockets, which means
+the Rails asset helpers are not available as Sass functions - this gem's
+stylesheet detects that and falls back to govuk-frontend's own
+`$govuk-assets-path`, but any application stylesheet calling `image-url` or
+`font-url` would need rewriting. Serving the prebuilt
+`vendor/assets/stylesheets/govuk-frontend.min.css` and dropping SCSS compilation
+altogether is a third option, but it gives up the settings, tools and helpers
+that application stylesheets use.
+
+Dart Sass warns that `@import` is deprecated. Sprockets stylesheets are built on
+`@import`, so until Rails' asset pipeline moves to `@use` these warnings are
+expected. Silence them per application with:
+
+```ruby
+config.sass.silence_deprecations = ["import"]
 ```
 
+[dartsass-sprockets]: https://github.com/tablecheck/dartsass-sprockets
+
+### govuk_design_system_formbuilder
+
+Pin `govuk_design_system_formbuilder` to `~> 6.4.0`. That is the release that
+tracks govuk-frontend 6.4.0; earlier 6.x releases target earlier govuk-frontend
+6.x versions, and 5.x emits govuk-frontend 5 markup.
+
+### Content Security Policy
+
+govuk-frontend gates over a hundred CSS rule blocks and all of its component
+JavaScript on the `govuk-frontend-supported` class, and `initAll()` raises a
+`SupportError` if the class is absent. Upstream's template sets it from an
+inline `<script>`, which a strict `script-src` blocks.
+
+This gem instead ships that one statement as an asset,
+`defra_ruby_template_supported.js`, and the layout includes it at the top of
+`<body>`. No inline script is used, so no `unsafe-inline` or nonce is needed for
+it.
+
+## Upgrading from 5.x
+
+1. Move the application to a Dart Sass pipeline (see above).
+2. Update `govuk_design_system_formbuilder` to `~> 6.4.0`.
+3. Replace the contents of the `:header_content` slot (see below).
+4. Check any application stylesheet or markup using classes govuk-frontend 6
+   removed - `govuk-template--rebranded`, `govuk-header__content`,
+   `govuk-header__link`, `govuk-header__service-name`,
+   `govuk-header__navigation*`, `govuk-header__menu-button` and
+   `govuk-header__link--homepage`.
+
+### Service navigation
+
+govuk-frontend 6 removed the service name and navigation from the header
+component. `govuk-service-navigation` replaces them and renders as a sibling of
+the header rather than inside it.
+
+The `:header_content` slot is kept under its existing name - all six consuming
+applications fill it - but it has moved to that position, and the classes
+applications used to put in it no longer exist. Fill it with service navigation
+markup instead:
+
+```erb
+<% content_for :header_content do %>
+  <section aria-label="Service information"
+           class="govuk-service-navigation"
+           data-module="govuk-service-navigation">
+    <div class="govuk-width-container">
+      <div class="govuk-service-navigation__container">
+        <span class="govuk-service-navigation__service-name">
+          <%= link_to t(:global_proposition_header),
+                      main_app.root_path,
+                      class: "govuk-service-navigation__link" %>
+        </span>
+      </div>
+    </div>
+  </section>
+<% end %>
+```
 
 ## Updating the govuk-frontend
 
 To update to the latest govuk-frontend files:
 
+```bash
+npm install govuk-frontend@<version> --save
 ```
-$ npm install govuk-frontend --save
-$ rake
+
+```bash
+bundle exec rake
 ```
 
-Then update the [`DefraRubyTemplate::Version`](https://github.com/DEFRA/defra-ruby-template/blob/main/lib/defra_ruby_template/version.rb) so that it matches the `govuk-frontend` [version](https://github.com/alphagov/govuk-frontend/tags).
+`rake` wipes and re-vendors everything under `vendor/assets`, so files that
+govuk-frontend has stopped shipping are removed rather than left behind. It also
+writes three files that are generated rather than copied:
+
+| File | Generated from |
+|------|----------------|
+| `vendor/assets/stylesheets/defra_ruby_template.scss` | the entry point applications import |
+| `vendor/assets/javascripts/defra_ruby_template_supported.js` | the inline script in govuk-frontend's `template.njk` |
+| `vendor/assets/assets/manifest.json.erb` | govuk-frontend's `manifest.json`, with its icon paths rewritten to `asset_path` |
+
+Then:
 
+1. Re-render govuk-frontend's `dist/govuk/template.njk` and port any changes into
+   `app/views/layouts/defra_ruby_template.html.erb`.
+2. Update [`DefraRubyTemplate::VERSION`](lib/defra_ruby_template/version.rb) to
+   match the govuk-frontend [version](https://github.com/alphagov/govuk-frontend/tags).
 
 ## Contributing
 

data/Rakefile

@@ -3,13 +3,31 @@
 require "bundler/gem_tasks"
 require "defra_ruby_template/version"
 
+DIST = "node_modules/govuk-frontend/dist/govuk"
+
+# Everything under these paths is generated by the tasks below, so it is wiped
+# first. Without this, files that govuk-frontend has since removed (v5's
+# all.scss, the pre-v5 crest PNGs, the v5 rebrand/ asset directory) survive
+# forever and the vendored copy drifts away from the release it claims to be.
+GENERATED_PATHS = %w[
+  vendor/assets/assets
+  vendor/assets/fonts
+  vendor/assets/images
+  vendor/assets/javascripts/defra_ruby_template.js
+  vendor/assets/javascripts/defra_ruby_template_supported.js
+  vendor/assets/stylesheets
+].freeze
+
 task default: :assets
 
+desc "Vendor every govuk-frontend asset the gem ships"
 task "assets" do
   %w[
+    clean
     minified_css
     fonts
     images
+    manifest
     stylesheets
     javascripts
   ].each do |task_name|
@@ -19,52 +37,158 @@ end
 
 def copy_assets(source_pattern, target_replacement)
   Rake::FileList[source_pattern].each do |source|
-    target = source.sub("node_modules/govuk-frontend/dist/govuk", target_replacement)
-    mkdir_p(File.dirname(target))
+    target = source.sub(DIST, target_replacement)
+    ensure_directory_for(target)
     copy_file source, target
   end
 end
 
+# govuk-frontend ships hundreds of files across a handful of directories, and an
+# unconditional mkdir_p logs a line for every one of them.
+def ensure_directory_for(target)
+  directory = File.dirname(target)
+  mkdir_p(directory) unless File.directory?(directory)
+end
+
+desc "Remove the vendored assets so no file outlives the release that shipped it"
+task "clean" do
+  GENERATED_PATHS.each { |path| rm_rf(path) }
+end
+
+desc "Vendor the prebuilt govuk-frontend stylesheet"
 task "minified_css" do
-  copy_assets("node_modules/govuk-frontend/dist/govuk/govuk-frontend.min.css", "vendor/assets/stylesheets")
+  copy_assets("#{DIST}/govuk-frontend.min.css", "vendor/assets/stylesheets")
 end
 
+desc "Vendor the govuk-frontend Sass and write the gem stylesheet entry point"
 task "stylesheets" do
-  copy_assets("node_modules/govuk-frontend/dist/govuk/**/*.scss", "vendor/assets/stylesheets")
+  copy_assets("#{DIST}/**/*.scss", "vendor/assets/stylesheets")
   create_scss_file
 end
 
+# Fonts and images are vendored twice, under two different Sprockets load paths:
+#
+#   vendor/assets/{fonts,images}  -> logical paths "light-....woff2", "favicon.ico"
+#   vendor/assets/assets/*        -> logical paths "fonts/light-....woff2", "images/favicon.ico"
+#
+# The first is what font-url()/image-url() and the layout's asset_path resolve
+# against. The second backs govuk-frontend's own default $govuk-assets-path of
+# "/assets/", which manifest.json's relative icon paths also rely on.
+desc "Vendor the GDS Transport fonts"
 task "fonts" do
-  copy_assets("node_modules/govuk-frontend/dist/govuk/assets/fonts/*.{eot,woff,woff2,ico,svg}", "vendor")
+  copy_assets("#{DIST}/assets/fonts/*.{eot,woff,woff2,ico,svg}", "vendor")
+  copy_assets("#{DIST}/assets/fonts/*.{eot,woff,woff2,ico,svg}", "vendor/assets")
 end
 
+desc "Vendor the GOV.UK icons and images"
 task "images" do
-  copy_assets("node_modules/govuk-frontend/dist/govuk/assets/images/*.{png,gif,jpg,ico,svg}", "vendor")
+  copy_assets("#{DIST}/assets/images/*.{png,gif,jpg,ico,svg}", "vendor")
+  copy_assets("#{DIST}/assets/images/*.{png,gif,jpg,ico,svg}", "vendor/assets")
 end
 
+# govuk-frontend 6's template links a web app manifest, and the manifest points
+# at its icons with paths relative to itself ("images/favicon.ico"). Sprockets
+# serves digested filenames in production, so those relative paths would 404.
+# Vendor it as an ERB template instead and let Sprockets resolve each icon.
+desc "Vendor the web app manifest as an asset pipeline template"
+task "manifest" do
+  source = "#{DIST}/assets/manifest.json"
+  target = "vendor/assets/assets/manifest.json.erb"
+
+  content = File.read(source).gsub(%r{"src": "images/([^"]+)"}) do
+    %("src": "<%= asset_path "#{Regexp.last_match(1)}" %>")
+  end
+
+  raise "No icon paths were rewritten in #{source}" unless content.include?("asset_path")
+
+  ensure_directory_for(target)
+  File.write(target, content)
+end
+
+desc "Vendor the govuk-frontend bundle and the govuk-frontend-supported snippet"
 task "javascripts" do
-  Rake::FileList["node_modules/govuk-frontend/dist/govuk/all.bundle.js"].each do |source|
-    target = source.sub("node_modules/govuk-frontend/dist/govuk", "vendor/assets/javascripts")
+  Rake::FileList["#{DIST}/all.bundle.js"].each do |source|
+    target = source.sub(DIST, "vendor/assets/javascripts")
     target = target.sub("all.bundle.js", "defra_ruby_template.js")
-    mkdir_p(File.dirname(target))
+    ensure_directory_for(target)
     copy_file source, target
   end
+
+  create_supported_js_file
 end
 
+# govuk-frontend's own entry point (index.scss) is a Sass module: it uses
+# @use/@forward and ships sibling *.import.scss shims for @import callers. Both
+# need Dart Sass - LibSass does not implement the module system and quietly
+# emits the @use rules as literal CSS, producing a stylesheet with no styles in
+# it. Consuming apps import this file, so all it does is point the asset URL
+# helpers at Sprockets (when Sprockets is what is compiling it) and hand over to
+# govuk-frontend.
+#
+# It deliberately no longer wraps govuk-frontend's all.scss, which exists only
+# to emit an "Importing using 'govuk/all' is deprecated" warning on every
+# compile.
+SCSS_ENTRY_POINT = <<~SCSS
+  // Compiled through Sprockets (sassc-rails, dartsass-sprockets) the Rails
+  // asset helpers are registered as Sass functions, so hand govuk-frontend
+  // their names and asset URLs resolve to digest paths. Compiled standalone
+  // (dartsass-rails, a plain `sass` run) they do not exist, and govuk-frontend
+  // falls back to $govuk-images-path / $govuk-fonts-path.
+  //
+  // The variables are declared before the @if so that the assignment inside it
+  // updates the global rather than creating one scoped to the @if.
+  @use "sass:meta";
+
+  $govuk-image-url-function: null;
+  $govuk-font-url-function: null;
+
+  @if meta.function-exists("image-url") {
+    $govuk-image-url-function: "image-url";
+  }
+
+  @if meta.function-exists("font-url") {
+    $govuk-font-url-function: "font-url";
+  }
+
+  // Passing the helpers by name is the only form available to @import users,
+  // and govuk-frontend deprecates it in favour of meta.get-function, which
+  // needs @use. Silence the warning until this file can be migrated.
+  $govuk-suppressed-warnings: ("image-url-string", "font-url-string");
+
+  // index.import rather than index: Dart Sass maps `@import "index"` onto
+  // index.import.scss itself, but Sprockets-based pipelines supply their own
+  // importer and resolve `index` to index.scss - the module entry point, which
+  // silently ignores the settings above and emits undigested asset URLs.
+  // Naming the shim explicitly makes both routes behave the same.
+  @import "index.import";
+SCSS
+
 def create_scss_file
-  content = <<~SCSS
-    // Using Rails with the asset pipeline so set the helper methods
-    $govuk-font-url-function: 'image-url';
-    $govuk-image-url-function: 'font-url';
-    
-  SCSS
-
-  source_file = "node_modules/govuk-frontend/dist/govuk/all.scss"
   target_file = "vendor/assets/stylesheets/defra_ruby_template.scss"
 
-  mkdir_p(File.dirname(target_file))
-  File.open(target_file, "w") do |file|
-    file.write(content)
-    file.write(File.read(source_file))
-  end
+  ensure_directory_for(target_file)
+  File.write(target_file, SCSS_ENTRY_POINT)
+end
+
+# govuk-frontend gates 100+ CSS rule blocks and every component's JavaScript on
+# the govuk-frontend-supported class, and initAll() raises SupportError without
+# it. Upstream sets it from an inline script in template.njk, which a strict
+# script-src CSP blocks, so extract that one statement into an asset the layout
+# can include instead. Extracting rather than hardcoding keeps it honest if
+# upstream ever changes the statement.
+def create_supported_js_file
+  template = File.read("#{DIST}/template.njk")
+  snippet = template[%r{<script[^>]*>(document\.body\.className \+=.*?)</script>}m, 1]
+
+  raise "Could not find the js-enabled snippet in #{DIST}/template.njk" if snippet.nil?
+
+  target_file = "vendor/assets/javascripts/defra_ruby_template_supported.js"
+
+  ensure_directory_for(target_file)
+  File.write(target_file, <<~JS)
+    // Extracted from govuk-frontend's template.njk, where it is an inline
+    // <script> that a strict script-src Content-Security-Policy blocks.
+    // Generated by `rake javascripts` - do not edit by hand.
+    #{snippet.strip}
+  JS
 end