EES-5554 Fix accessibility issues in public API docs

src/explore-education-statistics-api-docs/source/partials/_parameter_table.html.erb

@@ -1,5 +1,9 @@
-<div aria-label="Parameters" class="app-table-container" role="region" tabindex="0">
-  <table>
+<div <% if defined? labelled_by %>aria-labelledby="<%= labelled_by %>"<% end %>
+  class="app-table-container"
+  role="region"
+  tabindex="0"
+>
+  <table class="app-parameter-table">
     <thead>
     <tr>
       <th scope="col">Parameter</th>
@@ -14,7 +18,7 @@
         <td><code class="app-word-break--normal"><%= parameter.name %></code></td>
         <td><%= render_schema_type(parameter.schema) %></td>
         <td><%= parameter.required? %></td>
-        <td>
+        <td class="app-parameter-table__description">
           <%= partial("partials/schema_description", :locals => {
             description: parameter.description,
             schema: parameter.schema

src/explore-education-statistics-api-docs/source/stylesheets/app.scss

@@ -1,15 +1,6 @@
 .technical-documentation {
+  hyphens: auto;
   max-width: 50em;
-}
-
-.toc__list li {
-  a:link,
-  a:visited {
-    padding: 8px 10px;
-  }
-}
-
-.collapsible {
   word-break: break-word;
 }
 

src/explore-education-statistics-api-docs/source/stylesheets/components/_header.scss

@@ -0,0 +1,34 @@
+.app-header {
+  @include govuk-media-query($until: tablet) {
+    .govuk-header__container {
+      align-items: center;
+      display: flex;
+      flex-wrap: wrap;
+      justify-content: space-between;
+      padding: govuk-spacing(2) !important;
+    }
+
+    .govuk-header__logo {
+      padding-right: 0;
+      margin-bottom: govuk-spacing(1);
+    }
+
+    .govuk-header__content {
+      flex-grow: 1;
+    }
+
+    .govuk-header__navigation--end {
+      text-align: right;
+    }
+
+    .govuk-header__menu-button {
+      display: inline-block;
+      position: unset;
+    }
+
+    .govuk-header__navigation-list {
+      text-align: left;
+      width: 100%;
+    }
+  }
+}

src/explore-education-statistics-api-docs/source/stylesheets/components/_table.scss

@@ -1,4 +1,6 @@
 .app-table-container {
+  margin-bottom: govuk-spacing(4);
+
   &:focus {
     box-shadow: 0 0 0 2px;
     outline: $govuk-focus-width solid $govuk-focus-colour;
@@ -9,4 +11,17 @@
     display: block;
     overflow-x: auto;
   }
+
+  table {
+    margin-bottom: 0;
+  }
+}
+
+.app-parameter-table {
+  hyphens: none;
+  word-break: normal;
+
+  &__description {
+    min-width: 200px;
+  }
 }

src/explore-education-statistics-api-docs/source/stylesheets/components/_toc.scss

@@ -0,0 +1,62 @@
+.toc__list li {
+  a:link,
+  a:visited {
+    padding: 8px 10px;
+  }
+}
+
+.collapsible {
+  word-break: break-word;
+}
+
+@include govuk-media-query($until: tablet) {
+  .js .toc__list {
+    margin-right: 0;
+  }
+
+  /* stylelint-disable selector-max-compound-selectors */
+  .js .toc li li li {
+    display: initial;
+
+    a {
+      padding-left: govuk-spacing(3);
+    }
+  }
+  /* stylelint-enable selector-max-compound-selectors */
+
+  .collapsible {
+    align-items: center;
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: space-between;
+  }
+
+  .collapsible__toggle {
+    align-items: center;
+    display: flex;
+    height: 30px;
+    justify-content: center;
+    right: 0;
+    top: 5px;
+    width: 20px;
+  }
+
+  .collapsible__toggle-icon {
+    position: relative;
+    top: -5px;
+    right: unset;
+  }
+
+  .collapsible__toggle-label {
+    position: absolute;
+  }
+
+  .collapsible__body {
+    word-break: break-all;
+    width: 100%;
+
+    a {
+      width: fit-content;
+    }
+  }
+}

src/explore-education-statistics-api-docs/source/stylesheets/screen.css.scss

@@ -6,4 +6,6 @@
 @import './utils';
 
 @import './components/copy';
+@import './components/header';
 @import './components/table';
+@import './components/toc';

src/explore-education-statistics-api-docs/source/templates/reference/endpoint.html.md.erb

@@ -23,22 +23,31 @@ The URL for this endpoint is:
 
 The following parameters will need to be substituted into the URL path.
 
-<%= partial("partials/parameter_table", :locals => { parameters: path_parameters }) %>
+<%= partial("partials/parameter_table", :locals => {
+  labelled_by: "path-parameters",
+  parameters: path_parameters })
+%>
 <% end %>
 
 <% query_parameters = parameters.select { |parameter| parameter.in == "query" } %>
 
 <% if query_parameters.any? %>
 ### Query parameters
 
-<%= partial("partials/parameter_table", :locals => { parameters: query_parameters }) %>
+<%= partial("partials/parameter_table", :locals => {
+  labelled_by: "query-parameters",
+  parameters: query_parameters }) %>
 <% end %>
 
 <% headers = parameters.select { |parameter| parameter.in == "header" } %>
 
 <% if headers.any? %>
 ### Headers
-<%= partial("partials/parameter_table", :locals => { parameters: headers }) %>
+
+<%= partial("partials/parameter_table", :locals => {
+  labelled_by: "headers",
+  parameters: headers
+}) %>
 <% end %>
 <% end %>
 
@@ -54,31 +63,33 @@ body_schema = schema.type.nil? && schema.all_of&.count == 1 ? schema.all_of[0] :
 body_parameters = get_schema_properties(schema)
 %>
 
-<table>
-  <thead>
-  <tr>
-    <th scope="col">Name</th>
-    <th scope="col">Type</th>
-    <th scope="col">Required</th>
-    <th scope="col">Description</th>
-  </tr>
-  </thead>
-  <tbody>
-  <% body_parameters.each do |name, parameter| %>
+<div aria-label="Request body properties" class="app-table-container" role="region" tabindex="0">
+  <table class="app-parameter-table">
+    <thead>
     <tr>
-      <td><code class="app-word-break--normal"><%= name %></code></td>
-      <td><%= render_schema_type(parameter) %></td>
-      <td><%= body_schema.requires?(parameter) %></td>
-      <td>
-        <%= partial("partials/schema_description", :locals => {
-          description: parameter.description,
-          schema: parameter
-        }) %>
-      </td>
+      <th scope="col">Name</th>
+      <th scope="col">Type</th>
+      <th scope="col">Required</th>
+      <th scope="col">Description</th>
     </tr>
-  <% end %>
-  </tbody>
-</table>
+    </thead>
+    <tbody>
+    <% body_parameters.each do |name, parameter| %>
+      <tr>
+        <td><code class="app-word-break--normal"><%= name %></code></td>
+        <td><%= render_schema_type(parameter) %></td>
+        <td><%= body_schema.requires?(parameter) %></td>
+        <td>
+          <%= partial("partials/schema_description", :locals => {
+            description: parameter.description,
+            schema: parameter
+          }) %>
+        </td>
+      </tr>
+    <% end %>
+    </tbody>
+  </table>
+</div>
 
 ### Example request body
 
@@ -141,32 +152,34 @@ languages.
 <% if responses.any? %>
 ## Responses
 
-<table>
-  <thead>
-  <tr>
-    <th scope="col">Status</th>
-    <th scope="col">Description</th>
-    <th scope="col">Media Type</th>
-    <th scope="col">Schema</th>
-  </tr>
-  </thead>
-  <tbody>
-<% responses.each do |status, response| %>
-<% response.content.each do |media_type, content| %>
+<div aria-labelledby="responses" class="app-table-container" role="region" tabindex="0">
+  <table class="app-parameter-table">
+    <thead>
     <tr>
-      <td><%= status %></td>
-      <td><%= render_markdown(response.description) %></td>
-      <td>
-        <%= media_type %>
-      </td>
-      <td>
-        <%= render_schema_type(content.schema) %>
-      </td>
+      <th scope="col">Status</th>
+      <th scope="col">Description</th>
+      <th scope="col">Media Type</th>
+      <th scope="col">Schema</th>
     </tr>
-<% end %>
-<% end %>
-  </tbody>
-</table>
+    </thead>
+    <tbody>
+  <% responses.each do |status, response| %>
+  <% response.content.each do |media_type, content| %>
+      <tr>
+        <td><%= status %></td>
+        <td><%= render_markdown(response.description) %></td>
+        <td>
+          <%= media_type %>
+        </td>
+        <td>
+          <%= render_schema_type(content.schema) %>
+        </td>
+      </tr>
+  <% end %>
+  <% end %>
+    </tbody>
+  </table>
+</div>
 
 <% if responses[200] %>
 ### Example successful response

src/explore-education-statistics-api-docs/source/templates/reference/schema.html.md.erb

@@ -22,8 +22,8 @@ Allowed options:
 <% if properties.any? %>
 ## Properties
 
-<div aria-label="Properties" class="app-table-container" role="region" tabindex="0">
-  <table>
+<div aria-labelledby="properties" class="app-table-container" role="region" tabindex="0">
+  <table class="app-parameter-table">
     <thead>
     <tr>
       <th scope="col">Property</th>