defra_ruby_template 5.11.1 → 6.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b18c3753cd11670cbccc3060666920c45c14a50622fded9e9315f9d7f06b75d
-  data.tar.gz: 427165381fd99ca7735860917b67d27448fe6b5ce604891d2742a38570d610b5
+  metadata.gz: 42e02e87fae59b0d67acc88406a2d4505cb4a426bc04628ef7dacdb64fe87fcc
+  data.tar.gz: ef0fdc6b77bd8705ce78e87eafb34ab6490a83b552f776e9ee56fad049db301d
 SHA512:
-  metadata.gz: a3c034522d149d45e4be307e8bafe4751782543e2dc749876a77b84ab9851a070a2eabe4ba6afdea815b977723f659fd50197bbb75eeca78c84d943ea9917773
-  data.tar.gz: 2535e72aae16ff75df074be99f4e4330c04151b4df4c10871f6b8cd3845bd72f1e12488de5a14074656b4e46288c4f65ee183f55ddc40951a1eacb33fe4ad306
+  metadata.gz: f421d6f36948c6ed6d2b8fcd536ed45ad6d70503b7b7388b77fa8f850afe073bde4b7091f1861c5e798a1d027c07c0706cd8a0d94351b5607d5effceaae20f49
+  data.tar.gz: 422abfcd9c4f675fc454e8569f46adeb933ff78715e7693db336afb11b11abd46fc4594a6f6d51d7b6f2470cc7a5a18a12793da3be44907fe832db1314bc9850

data/README.md

@@ -9,6 +9,10 @@
 
 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 major and minor version track the version of govuk-frontend it
+vendors, so 6.6.x of this gem ships govuk-frontend 6.6.0. Patch releases are
+changes to the gem itself.
+
 ## Installation
 
 Add this line to the application's Gemfile:
@@ -23,12 +27,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 +40,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 +61,192 @@ This gem includes the `defra_ruby_template` layout, and can be included  in a Ra
 <% end %>
 
 <%= render template: "layouts/defra_ruby_template" %>
+```
 
+### Stylesheets
+
+The gem's stylesheet entry point is a Sass module. Load it from the
+application's own stylesheet with `@use`:
+
+```scss
+@use "defra_ruby_template" as *;
+```
+
+That emits govuk-frontend's CSS and makes its settings, tools and helpers
+available unprefixed, the way `@import` did - `govuk-colour`, `govuk-font`,
+`$govuk-text-colour` and so on. The same rule configures govuk-frontend's own
+settings:
+
+```scss
+@use "defra_ruby_template" as * with (
+  $govuk-assets-path: "/custom-assets/"
+);
 ```
 
+Unlike `@import`, a `@use` applies only to the file it appears in, and it has
+to come before any other rule in that file. A partial that is still
+`@import`ed is pulled into the importing file's scope, so it keeps working
+untouched - only a partial loaded with `@use` needs its own `@use` line.
+
+## 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` will not work. It compiles outside Sprockets, so the Rails
+asset helpers are not registered as Sass functions and this gem's stylesheet
+fails to compile. Serving the prebuilt
+`vendor/assets/stylesheets/govuk-frontend.min.css` and dropping SCSS compilation
+altogether is the other option, but it gives up the settings, tools and helpers
+that application stylesheets use.
+
+Dart Sass warns that `@import` is deprecated. Nothing the gem ships uses it, so
+an application that loads the gem with `@use` and has converted its own
+partials does not need `config.sass.silence_deprecations = ["import"]`.
+
+[dartsass-sprockets]: https://github.com/tablecheck/dartsass-sprockets
+
+### govuk_design_system_formbuilder
+
+Pin `govuk_design_system_formbuilder` to `~> 6.6.0`. That is the release that
+tracks govuk-frontend 6.6.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 6.4.0
+
+6.6.0 vendors govuk-frontend 6.6.0, and turns the stylesheet entry point from
+an `@import` shim into a Sass module so that neither Sass nor govuk-frontend
+emits a deprecation warning. The gem now only compiles under Sprockets, which
+is what registers the Rails asset helpers as Sass functions.
+
+In each application:
+
+1. Pin `govuk_design_system_formbuilder` to `~> 6.6.0`.
+2. Replace `@import "defra_ruby_template"` with `@use "defra_ruby_template" as *`
+   at the top of the stylesheet. Partials it `@import`s keep working as they are.
+3. Convert those `@import`s to `@use` too, giving each partial that uses
+   govuk-frontend's settings, tools or helpers its own `@use` line.
+4. Drop `config.sass.silence_deprecations = ["import"]`.
+
+`@import "defra_ruby_template"` still works, so the steps can be taken
+separately, but it keeps the deprecation warning.
+
+govuk-frontend 6.5 and 6.6 carry no breaking changes. They add the Language
+navigation and Feedback components, both in trial status, and deprecate three
+organisation colours following the July 2026 machinery of government changes.
+
+### Deprecated colour names
+
+govuk-frontend 6 renamed the colour palette. The old names still resolve, but
+each one warns - replace them with the name the warning gives, for example
+`govuk-colour("black", $variant: "tint-95")` for `govuk-colour("light-grey")`.
+
+Adding `pre-brand-colour` to `$govuk-suppressed-warnings` does not silence it:
+govuk-frontend 6.6.0 calls an undefined `_should-warn()` in
+`helpers/_colour.scss`, which Sass falls back to treating as a plain CSS
+function, so the suppression check is always true.
+
+## Upgrading from 5.x
+
+1. Move the application to a Dart Sass pipeline (see above).
+2. Update `govuk_design_system_formbuilder` to `~> 6.6.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 load |
+| `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,135 @@ 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 load this file, so all it does is point the asset URL
+# helpers at Sprockets 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
+  // The gem is compiled through Sprockets (dartsass-sprockets), which registers
+  // the Rails asset helpers as Sass functions. Handing govuk-frontend references
+  // to them is what makes asset URLs come out as digest paths. Compiling this
+  // file outside Sprockets is not supported - meta.get-function raises there.
+  @use "sass:meta";
+
+  @forward "index" with (
+    $govuk-image-url-function: meta.get-function("image-url"),
+    $govuk-font-url-function: meta.get-function("font-url")
+  );
+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