govuk_tech_docs 2.1.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50a30563bccb5eebe08dd7ca913942ec7d95f085566905070e32e204fadfa5e2
-  data.tar.gz: 81a9b36062450e9d6249d9dfd396ed14e751a8593a4fbe42f76a93808ead4598
+  metadata.gz: 4adec245cbbc73fe2a14f73eb4a0eb2f9acf4d8d751f0786271c59f479c8b244
+  data.tar.gz: 9017c133a8dace561bf56b4e2ec852b4dcdc15a341501b8784659f229f2f183a
 SHA512:
-  metadata.gz: 315652fdfc9bbb68bf0730a81c424981d0de9e1bcfd4a751f9d728595c112cbe447134f07f25102da905b29719af9693412bd9292fc68b6005161b8dbdc09d2e
-  data.tar.gz: 2e5db9c081d29b802c3acd097a0ab3c5920e7e3f38e1dac09679b78676532532b330743d5a806743491c38b4aef1b9796137fb701e4e7cf592a86a0fa09c003d
+  metadata.gz: 3da0c05902288480bf1953b7d5ad275742707cb8324cebe68a1f970cb9dda1b2c70a6538aa9af7a6272973e4b08b3a10108ad6591cbb78bae5aa4e46d436357d
+  data.tar.gz: 1ca0540c1625e80f25d89426f893d15368da0c13b84e5824c4808abd62bfed7bf1e4b93738c2ecd76fe43d70fd23b5517494078ab94367f062f4a73f8c0cec8f

data/.github/pull_request_template.md

@@ -0,0 +1 @@
+⚠️ Don't forget to update the gem version in the [CHANGELOG](https://github.com/alphagov/tech-docs-gem/blob/master/CHANGELOG.md) before merging! When you're ready to release bump [version file](https://github.com/alphagov/tech-docs-gem/blob/master/lib/govuk_tech_docs/version.rb) and generate a tag. ⚠️

data/.travis.yml

@@ -1,4 +1,7 @@
 language: ruby
+cache:
+  bundler: true
+  npm: true
 before_install:
   - gem update --system
   - gem install bundler

data/CHANGELOG.md

@@ -1,12 +1,20 @@
 # Changelog
 
-## Unreleased
+## 2.2.0
 
-### Ruby version bump
+### Accessibility Fixes
 
-We've updated the Ruby version supported:
+- [#205: Improve table of contents accessibility](https://github.com/alphagov/tech-docs-gem/pull/205)
+- [#209: Some search and keyboard navigation updates](https://github.com/alphagov/tech-docs-gem/pull/209)
+- [#210: Stop linking images to new tabs](https://github.com/alphagov/tech-docs-gem/pull/210)
+- [#214: Implement row level table headings to allow accessible tables with row headings](https://github.com/alphagov/tech-docs-gem/pull/214)
+- [#215: Add tabindex and focus states to code blocks](https://github.com/alphagov/tech-docs-gem/pull/215)
 
-- [#201: Bump ruby to 2.7.2](https://github.com/alphagov/tech-docs-gem/pull/201)
+### Docs
+
+- [#206: Remove tdt docs content from readme file](https://github.com/alphagov/tech-docs-gem/pull/206)
+
+## 2.1.1
 
 ### Fixes
 
@@ -14,6 +22,12 @@ We’ve made fixes in the following pull requests:
 
 - [#199: Fix page expiry box link colours (hover and focus) ](https://github.com/alphagov/tech-docs-gem/pull/199)
 
+### Ruby version bump
+
+We've updated the Ruby version supported:
+
+- [#201: Bump ruby to 2.7.2](https://github.com/alphagov/tech-docs-gem/pull/201)
+
 ## 2.1.0
 
 ### New features

data/README.md

@@ -3,23 +3,19 @@
 This repo contains the Ruby gem that distributes the [Tech Docs Template][tdt-template]. The Tech Docs Template is a [middleman template][mmt] that
 you can use to build technical documentation using a GOV.UK style.
 
-👉 Find out more about the template and its features from the [Tech Docs Template documentation][tdt-docs].
-
-## Usage
-
-👉 Find out how to [generate a new website with the Tech Docs Template][tdt-readme].
+To find out more about setting up and managing content for a website using this template, see the [Tech Docs Template documentation][tdt-docs].
 
 ## Contributing
 
 Everybody who uses this project is encouraged to contribute.
 
-👉 [See CONTRIBUTING.md](CONTRIBUTING.md) for guidance on making changes.
+You can find out more about contributing to this project from the[CONTRIBUTING.md file](CONTRIBUTING.md).
 
 ## GOV.UK frontend
 
 This gem uses [GOV.UK Frontend](https://github.com/alphagov/govuk-frontend), part of the [GOV.UK Design System](https://design-system.service.gov.uk/).
 
-We use `npm` to download the govuk-frontend package. To update to a new version, change the version in [package.json](blob/master/package.json) and run `npm update`.
+We use `npm` to download the govuk-frontend package. To update to a new version, change the version in the [package.json file](blob/master/package.json) and run `npm update`.
 
 ## Developing locally
 
@@ -30,19 +26,13 @@ There are 2 ways to develop with this gem. You can see your changes on either:
 
 ### Use your own Tech Docs Template website
 
-If you want to see how your changes to the gem affect your website, you have to point your site's Gemfile to your local checkout:
+To see how your changes to the gem affect your website, point your website's Gemfile to your local checkout:
 
 ```rb
 gem 'govuk_tech_docs', path: '../tech-docs-gem'
 ```
 
-To view your changes locally run:
-
-```sh
-bundle exec middleman server
-```
-
-See your website on `http://localhost:4567` in your browser.
+To preview your documentation changes locally, see the [Tech Docs Template documentation on previewing your documentation](https://tdt-documentation.london.cloudapps.digital/create_project/preview/#preview-your-documentation).
 
 ### Use the example in this repo
 
@@ -56,14 +46,16 @@ bundle exec middleman server
 
 See your website on `http://localhost:4567` in your browser.
 
+For more information on previewing your documentation locally, see the [Tech Docs template documentation on previewing your documentation](https://tdt-documentation.london.cloudapps.digital/create_project/preview/#preview-your-documentation).
+
 ## Tests
 
-The repository contains automated JavaScript tests that use [Jasmine][jas] test framework.
+This repository contains automated JavaScript tests that use the [Jasmine test framework][jas].
 
-To run the tests and see the results in your browser:
+You can run these tests and see the results in your browser.
 
-1. Run `bundle exec rake jasmine`
-2. Go to `http://localhost:8888` in your browser
+1. Run `bundle exec rake jasmine`.
+2. Go to `http://localhost:8888` in your browser.
 
 To run the tests and see the results in your terminal, run:
 
@@ -73,14 +65,15 @@ bundle exec rake jasmine:ci
 
 ## Releasing new versions
 
-To release a new version, create a new Pull Request that updates [version.rb](lib/govuk_tech_docs/version.rb) and [CHANGELOG.md](CHANGELOG.md). Don't mix this in with other changes - this makes it easier to find out what was released when. See [this PR to release a new version as an example](https://github.com/alphagov/tech-docs-gem/pull/15).
+To release a new version, create a new pull request (PR) that updates [version.rb](lib/govuk_tech_docs/version.rb) and [CHANGELOG.md](CHANGELOG.md).
+
+Do not include other changes in your pull request, as this makes it easier to find out what was released when. See an example of a [PR for releasing a new version](https://github.com/alphagov/tech-docs-gem/pull/15).
 
 Travis will automatically release a [new version to Rubygems.org](https://rubygems.org/gems/govuk_tech_docs).
 
 ## Licence
 
-Unless stated otherwise, the codebase is released under [the MIT License][mit].
-This covers both the codebase and any sample code in the documentation.
+Unless stated otherwise, the codebase is released under [the MIT License][mit]. This covers both the codebase and any sample code in the documentation.
 
 The documentation is [© Crown copyright][copyright] and available under the terms of the [Open Government 3.0][ogl] licence.
 

data/lib/assets/javascripts/_modules/search.js

@@ -6,6 +6,7 @@
   Modules.Search = function Search () {
     var s = this
     var $html = $('html')
+    var $tocNav
     var $searchForm
     var $searchLabel
     var $searchInput
@@ -26,6 +27,7 @@
       $searchResults = $searchResultsWrapper.find('.search-results__content')
       $searchResultsTitle = $searchResultsWrapper.find('.search-results__title')
       $searchResultsClose = $searchResultsWrapper.find('.search-results__close')
+      $tocNav = $('#toc')
       s.downloadSearchIndex()
       attach()
       changeSearchLabel()
@@ -67,7 +69,14 @@
       $searchForm.on('submit', function (e) {
         e.preventDefault()
         showResults()
-        $searchResults.find('.search-result__title a').first().focus()
+        var $firstResult = $searchResults.find('.search-result__title a').first()
+        if ($firstResult.length) {
+          $firstResult.focus()
+        } else {
+          // if there are no results, show the "0 results" state
+          results = []
+          updateTitle()
+        }
       })
 
       // Closing the search results, move focus back to the search input
@@ -98,7 +107,7 @@
     }
 
     function changeSearchLabel () {
-      $searchLabel.text('Search')
+      $searchLabel.text('Search this documentation')
     }
 
     function getResults (query) {
@@ -192,12 +201,14 @@
       $searchResultsWrapper.addClass('is-open')
         .attr('aria-hidden', 'false')
       $html.addClass('has-search-results-open')
+      $tocNav.addClass('search-results-open')
     }
 
     function hideResults () {
       $searchResultsWrapper.removeClass('is-open')
         .attr('aria-hidden', 'true')
       $html.removeClass('has-search-results-open')
+      $tocNav.removeClass('search-results-open')
     }
 
     function sendQueryToAnalytics () {

data/lib/assets/javascripts/_modules/table-of-contents.js

@@ -7,23 +7,22 @@
     var $toc
     var $tocList
 
-    var $openLink
-    var $closeLink
+    var $openButton
+    var $closeButton
 
     this.start = function ($element) {
       $toc = $element
       $tocList = $toc.find('.js-toc-list')
-
       // Open link is not inside the module
-      $openLink = $html.find('.js-toc-show')
-      $closeLink = $toc.find('.js-toc-close')
+      $openButton = $html.find('.js-toc-show')
+      $closeButton = $toc.find('.js-toc-close')
 
       fixRubberBandingInIOS()
       updateAriaAttributes()
 
       // Need delegated handler for show link as sticky polyfill recreates element
-      $openLink.on('click.toc', preventingScrolling(openNavigation))
-      $closeLink.on('click.toc', preventingScrolling(closeNavigation))
+      $openButton.on('click.toc', preventingScrolling(openNavigation))
+      $closeButton.on('click.toc', preventingScrolling(closeNavigation))
       $tocList.on('click.toc', 'a', closeNavigation)
 
       // Allow aria hidden to be updated when resizing from mobile to desktop or
@@ -65,21 +64,17 @@
 
       toggleBackgroundVisiblity(false)
       updateAriaAttributes()
-
-      focusFirstLinkInToc()
+      $toc.focus()
     }
 
     function closeNavigation () {
       $html.removeClass('toc-open')
+      $html.removeClass('has-search-results-open')
 
       toggleBackgroundVisiblity(true)
       updateAriaAttributes()
     }
 
-    function focusFirstLinkInToc () {
-      $('a', $tocList).first().focus()
-    }
-
     function toggleBackgroundVisiblity (visibility) {
       $('.toc-open-disabled').attr('aria-hidden', visibility ? '' : 'true')
     }
@@ -87,7 +82,7 @@
     function updateAriaAttributes () {
       var tocIsVisible = $toc.is(':visible')
 
-      $($openLink).add($closeLink)
+      $($openButton).add($closeButton)
         .attr('aria-expanded', tocIsVisible ? 'true' : 'false')
 
       $toc.attr('aria-hidden', tocIsVisible ? 'false' : 'true')

data/lib/assets/stylesheets/modules/_search.scss

@@ -1,16 +1,9 @@
+$input-size: 40px;
+
 @include govuk-media-query($media-type: screen) {
   .page-title + .search {
     margin-top: govuk-spacing(6);
   }
-
-  .js .search__label {
-    position: absolute;
-    left: -9999em;
-    top: auto;
-    width: 1px;
-    height: 1px;
-    overflow: hidden;
-  }
 }
 
 @include govuk-media-query($media-type: print) {
@@ -19,6 +12,46 @@
   }
 }
 
+.js .search__label {
+  @extend .govuk-visually-hidden;
+}
+
+.search__form {
+  position: relative;
+}
+
+.search__input {
+  width: 230px;
+  width: calc(100% - #{$input-size});
+}
+
+.search__button {
+  position: absolute;
+  bottom: 0;
+  right: 0;
+  border: 0;
+  background-color: govuk-colour('blue');
+  color: #fff;
+  cursor: pointer;
+  padding: 0;
+  width: $input-size;
+  height: 100%;
+  background-image: url('/images/search-button.png');
+  background-repeat: no-repeat;
+  background-position: 2px 50%;
+  text-indent: -5000px;
+  overflow: hidden;
+  &:focus {
+    outline: $govuk-focus-width solid $govuk-focus-colour;
+    outline-offset: 0;
+    box-shadow: inset 0 0 0 $govuk-border-width-form-element * 2 govuk-colour("black");
+
+    @include govuk-if-ie8 {
+      border-width: $govuk-border-width-form-element * 2;
+    }
+  }
+}
+
 html.has-search-results-open {
   overflow: hidden;
   .app-pane__content {
@@ -47,6 +80,7 @@ html.has-search-results-open {
       top: 0;
       // The width of the sidebar
       left: 330px;
+      min-height: auto;
     }
 
     a:link, a:visited {

data/lib/assets/stylesheets/modules/_technical-documentation.scss

@@ -118,11 +118,20 @@
   }
 
   pre {
+    $padding: 15px;
+    $border-width: 1px;
+
     background: $code-00;
-    padding: 15px;
+    padding: $padding;
     overflow: auto;
     position: relative;
-    border: 1px solid $code-02;
+    border: $border-width solid $code-02;
+
+    &:focus {
+      padding: $padding - ($govuk-focus-width - $border-width);
+      border: $govuk-focus-width solid $govuk-focus-text-colour;
+      outline: $govuk-focus-width solid $govuk-focus-colour;
+    }
   }
 
   pre code {

data/lib/assets/stylesheets/modules/_toc.scss

@@ -127,7 +127,7 @@
           display: block;
           position: relative;
           z-index: 10;
-
+          width: 100%;
           padding: govuk-spacing(3) govuk-spacing(3) 10px;
 
           background: govuk-colour("light-grey");
@@ -135,10 +135,12 @@
             background: transparentize(govuk-colour("light-grey"), 0.05);
             backdrop-filter: blur(2px);
           }
+          border: 0;
           border-bottom: 1px solid govuk-colour("mid-grey");
           box-shadow: 1px 1px 3px rgba(0, 0, 0, 0.1);
           color:  $govuk-text-colour;
           text-decoration: none;
+          text-align: left;
 
           &:focus {
             @include govuk-focused-text;
@@ -163,6 +165,9 @@
 
       .toc__list {
         margin-right: govuk-spacing(7);
+        &.search-results-open {
+          display: none;
+        }
       }
 
       .toc__close {
@@ -170,7 +175,7 @@
         position: sticky;
         right: 0;
         top: 0;
-
+        border: 0;
         float: right;
         width: 20px;
         height: 20px;
@@ -207,6 +212,10 @@
           height: 100%;
           overflow: hidden;
           pointer-events: none;
+          // set visibility hidden on the body when TOC is open
+          // this is a hack to prevent tabbing to out-of-view elements when the TOC is active
+          // it's preferable to keyboard trapping... probably.
+          visibility: hidden;
         }
 
         .toc-show {
@@ -214,6 +223,7 @@
         }
 
         .toc {
+          visibility: visible;
           display: block;
           pointer-events: auto;
           position: fixed;

data/lib/govuk_tech_docs/tech_docs_html_renderer.rb

@@ -20,7 +20,7 @@ module GovukTechDocs
     end
 
     def image(link, *args)
-      %(<a href="#{link}" target="_blank" rel="noopener noreferrer">#{super}</a>)
+      %(<a href="#{link}" rel="noopener noreferrer">#{super}</a>)
     end
 
     def table(header, body)
@@ -30,5 +30,79 @@ module GovukTechDocs
         </table>
       </div>)
     end
+
+    def table_row(body)
+      # Post-processing the table_cell HTML to implement row headings.
+      #
+      # Doing this in table_row instead of table_cell is a hack.
+      #
+      # Ideally, we'd use the table_cell callback like:
+      #
+      # def table_cell(content, alignment, header)
+      #   if header
+      #     "<th>#{content}</th>"
+      #   elsif content.start_with? "# "
+      #     "<th scope="row">#{content.sub(/^# /, "")}</th>"
+      #   else
+      #     "<td>#{content}</td>"
+      #   end
+      # end
+      #
+      # Sadly, Redcarpet's table_cell callback doesn't allow you to distinguish
+      # table cells and table headings until https://github.com/vmg/redcarpet/commit/27dfb2a738a23aadd286ac9e7ecd61c4545d29de
+      # (which is not yet released). This means we can't use the table_cell callback
+      # without breaking column headers, so we're having to hack it in table_row.
+
+      fragment = Nokogiri::HTML::DocumentFragment.parse(body)
+      fragment.children.each do |cell|
+        next unless cell.name == "td"
+        next if cell.children.empty?
+
+        first_child = cell.children.first
+        next unless first_child.text?
+
+        leading_text = first_child.content
+        next unless leading_text.start_with?("#")
+
+        cell.name = "th"
+        cell["scope"] = "row"
+        first_child.content = leading_text.sub(/# */, "")
+      end
+
+      tr = Nokogiri::XML::Node.new "tr", fragment
+      tr.children = fragment.children
+
+      tr.to_html
+    end
+
+    def block_code(text, lang)
+      if defined?(super)
+        # Post-processing the block_code HTML to implement tabbable code blocks.
+        #
+        # Middleman monkey patches the Middleman::Renderers::MiddlemanRedcarpetHTML
+        # to include Middleman::Syntax::RedcarpetCodeRenderer. This defines its own
+        # version of `block_code(text, lang)` which we can call with `super`.
+
+        fragment = Nokogiri::HTML::DocumentFragment.parse(super)
+        fragment.traverse do |element|
+          if element.name == "pre" && element["tabindex"].nil?
+            element["tabindex"] = "0"
+          end
+        end
+        fragment.to_html
+      else
+        # If syntax highlighting with redcarpet isn't enabled, super will not
+        # be `defined?`, so we can jump straight to rendering HTML ourselves.
+
+        fragment = Nokogiri::HTML::DocumentFragment.parse("")
+        pre = Nokogiri::XML::Node.new "pre", fragment
+        pre["tabindex"] = "0"
+        code = Nokogiri::XML::Node.new "code", fragment
+        code["class"] = lang
+        code.content = text
+        pre.add_child code
+        pre.to_html
+      end
+    end
   end
 end

data/lib/govuk_tech_docs/version.rb

@@ -1,3 +1,3 @@
 module GovukTechDocs
-  VERSION = "2.1.1".freeze
+  VERSION = "2.2.0".freeze
 end

data/lib/source/layouts/_search.erb

@@ -1,16 +1,22 @@
 <% if config[:tech_docs][:enable_search] %>
 <div class="search" data-module="search">
-  <form action="https://www.google.co.uk/search" method="get" role="search">
+  <form action="https://www.google.co.uk/search" method="get" role="search" class="search__form govuk-!-margin-bottom-4">
     <input type="hidden" name="as_sitesearch" value="<%= config[:tech_docs][:host] %>"/>
-    <label class="govuk-label search__label" for="search">
+    <label class="govuk-label search__label" for="search" aria-hidden="true">
       Search (via Google)
     </label>
-    <input class="govuk-input govuk-!-margin-bottom-4" id="search" name="q" type="text" aria-controls="search-results" placeholder="Search">
+    <input
+      type="text"
+      id="search" name="q"
+      class="govuk-input govuk-!-margin-bottom-0 search__input"
+      aria-controls="search-results"
+      placeholder="Search">
+    <button type="submit" class="govuk-button search__button">Search</button>
   </form>
   <div id="search-results" class="search-results" aria-hidden="true" role="dialog" aria-labelledby="search-results-title">
     <div class="search-results__inner">
       <button class="search-results__close">Close<span class="search-results__close-label"> search results</span></button>
-      <h2 id="search-results-title" class="search-results__title" aria-live="polite">Results</h2>
+      <h2 id="search-results-title" class="search-results__title" aria-live="assertive" role="alert">Results</h2>
       <div class="search-results__content"></div>
     </div>
   </div>

data/lib/source/layouts/core.erb

@@ -34,18 +34,18 @@
 
       <% if content_for? :sidebar %>
         <div id="toc-heading" class="toc-show fixedsticky">
-          <a href="#toc" class="toc-show__label js-toc-show" aria-controls="toc">
+          <button type="button" class="toc-show__label js-toc-show" aria-controls="toc">
             Table of contents <span class="toc-show__icon"></span>
-          </a>
+          </button>
         </div>
       <% end %>
 
       <div class="app-pane__body"<%= " data-module=\"#{yield_content(:toc_module)}\"" if content_for? :toc_module %>>
         <% if content_for? :sidebar %>
           <div class="app-pane__toc">
-            <div class="toc" data-module="table-of-contents">
+            <div class="toc" data-module="table-of-contents" tabindex="-1" aria-label="Table of contents" role="dialog">
               <%= partial "layouts/search" %>
-              <a href="#" class="toc__close js-toc-close" aria-controls="toc" aria-label="Hide table of contents"></a>
+              <button type="button" class="toc__close js-toc-close" aria-controls="toc" aria-label="Hide table of contents"></button>
               <nav id="toc" class="js-toc-list toc__list" aria-labelledby="toc-heading"<%= " data-module=\"collapsible-navigation\"" if config[:tech_docs][:collapsible_nav] %>>
                 <%= yield_content :sidebar %>
               </nav>

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: govuk_tech_docs
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 2.2.0
 platform: ruby
 authors:
 - Government Digital Service
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-02-16 00:00:00.000000000 Z
+date: 2021-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -327,6 +327,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".editorconfig"
+- ".github/pull_request_template.md"
 - ".gitignore"
 - ".nvmrc"
 - ".rspec"
@@ -433,6 +434,7 @@ files:
 - lib/source/images/govuk-icn-close@2x.png
 - lib/source/images/govuk-icn-numbered-list.png
 - lib/source/images/govuk-icn-numbered-list@2x.png
+- lib/source/images/search-button.png
 - lib/source/images/search-result-caret.svg
 - lib/source/layouts/_analytics.erb
 - lib/source/layouts/_footer.erb