From 776f210e7b64e088d7ffaa8527c9d87c67aab9b8 Mon Sep 17 00:00:00 2001
From: Tom Byers <tombaromba@gmail.com>
Date: Tue, 15 Feb 2022 11:26:17 +0000
Subject: [PATCH] Add comments about deleting this code in future

If the :has pseudo-class becomes available in the
browsers we support in future, the code this
branch/pull request adds will be redundant as its
behaviour will be possible only using CSS.

This adds comments to note this to the parts of
the code you'd need to remove.
---
 app/assets/javascripts/main.js          |  4 ++++
 app/assets/javascripts/updateContent.js | 14 +++++++++++---
 2 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/app/assets/javascripts/main.js b/app/assets/javascripts/main.js
index 2d056032e..fb7869922 100644
--- a/app/assets/javascripts/main.js
+++ b/app/assets/javascripts/main.js
@@ -25,6 +25,10 @@ $(() => $('.govuk-header__container').on('click', function() {
   $(this).css('border-color', '#005ea5');
 }));
 
+// Applies our expanded focus style to the siblings of links when that link is wrapped in a heading.
+//
+// This will be possible in CSS in the future, using the :has pseudo-class. When :has is available
+// in the browsers we support, this code can be replaced with a CSS-only solution.
 $('.js-mark-focus-on-parent').on('focus blur', '*', e => {
   $target = $(e.target);
   if (e.type === 'focusin') {
diff --git a/app/assets/javascripts/updateContent.js b/app/assets/javascripts/updateContent.js
index c21287bfc..5c4f8fa6d 100644
--- a/app/assets/javascripts/updateContent.js
+++ b/app/assets/javascripts/updateContent.js
@@ -13,6 +13,10 @@
 
   // Methods to ensure the DOM fragment is clean of classes added by JS before diffing
   // and that they are replaced afterwards.
+  //
+  // Added to allow the use of JS, in main.js, to apply styles which in future could be
+  // achieved with the :has pseudo-class. If :has is available in our supported browsers,
+  // this can be removed in favour of a CSS-only solution.
   var classesPersister = {
     _classNames: [],
     _$els: [],
@@ -100,11 +104,15 @@
       var resource = $component.data('resource');
       var form = $component.data('form');
 
-      // replace component with contents
-      // the renderer does this anyway when diffing against the first response
+      // Replace component with contents.
+      // The renderer does this anyway when diffing against the first response
       $component.replaceWith($contents);
 
-      // store any classes that should persist through updates
+      // Store any classes that should persist through updates
+      //
+      // Added to allow the use of JS, in main.js, to apply styles which in future could be
+      // achieved with the :has pseudo-class. If :has is available in our supported browsers,
+      // this can be removed in favour of a CSS-only solution.
       if ($contents.data('classesToPersist') !== undefined) {
         $contents.data('classesToPersist')
           .split(' ')