Implement row level table headings to allow accessible tables with row headings

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - [#210: Fix issue with WCAG 2.1 success criterion 1.3.1 (Info and Relationships)](https://github.com/alphagov/tech-docs-gem/pull/210)
 - [#209: Some search and keyboard navigation updates](https://github.com/alphagov/tech-docs-gem/pull/209)
+- [#214: Implement row level table headings to allow accessible tables with row headings](https://github.com/alphagov/tech-docs-gem/pull/214)
 
 ### Ruby version bump
 

lib/govuk_tech_docs/tech_docs_html_renderer.rb

@@ -30,5 +30,49 @@ def table(header, body)
         </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
   end
 end

spec/govuk_tech_docs/tech_docs_html_renderer_spec.rb

@@ -0,0 +1,35 @@
+RSpec.describe GovukTechDocs::TechDocsHTMLRenderer do
+  describe "#render a table" do
+    it "renders tables with row headings" do
+      app = double("app")
+      context = double("context")
+      allow(context).to receive(:app) { app }
+      allow(app).to receive(:api)
+
+      processor = Redcarpet::Markdown.new(described_class.new(context: context), tables: true)
+      output = processor.render <<~MARKDOWN
+       |  A   | B |
+       |------|---|
+       |# C   | D |
+       |  E   | F |
+       |# *G* | H |
+      MARKDOWN
+
+      # Cells in the heading row should be treated as headings
+      expect(output).to include("<th>A</th>")
+      expect(output).to include("<th>B</th>")
+
+      # Cells starting with `#` should be treated as row headings
+      expect(output).to include('<th scope="row">C</th>')
+
+      # Cells starting with `#` with more complex markup should be treated as row headings
+      expect(output).to match(/<th scope="row"><em>G<\/em>\s*<\/th>/)
+
+      # Other cells should be treated as ordinary cells
+      expect(output).to include("<td>D</td>")
+      expect(output).to include("<td>E</td>")
+      expect(output).to include("<td>F</td>")
+      expect(output).to include("<td>H</td>")
+    end
+  end
+end