Restrict allowed tags for heading for Subhead and improve docs

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## main
 
+* **Breaking change:** Restrict `Subhead` `heading` slot tag to `div` and `h1`-`h6`.
+
+    *Kate Higa*
+
 * Deprecate `Flex` in favor of `BoxComponent`.
 
     *Manuel Puyol*

Rakefile

@@ -105,6 +105,10 @@ namespace :docs do
     "[Octicon](https://primer.style/octicons/)"
   end
 
+  def link_to_heading_practices
+    "[Learn more about best heading practices (WAI Headings)](https://www.w3.org/WAI/tutorials/page-structure/headings/)"
+  end
+
   def pretty_value(val)
     case val
     when nil

app/components/primer/blankslate_component.rb

@@ -4,7 +4,7 @@ module Primer
   # Use `Blankslate` when there is a lack of content within a page or section. Use as placeholder to tell users why something isn't there.
   # @accessibility
   #   `BlankSlate` renders an `<h3>` element for the title by default. Update the heading level based on what is appropriate for your page hierarchy by setting `title_tag`.
-  #   [Learn more about best heading practices (WAI Headings)](https://www.w3.org/WAI/tutorials/page-structure/headings/)
+  #   <%= link_to_heading_practices %>
   class BlankslateComponent < Primer::Component
     status :beta
 

app/components/primer/heading_component.rb

@@ -14,7 +14,7 @@ module Primer
   # @accessibility
   #   Headings convey semantic meaning. Assistive technology users rely on headings to quickly navigate and scan information on a page.
   #   Inappropriate use of headings can lead to a confusing experience.
-  #   [Learn more about best heading practices (WAI Headings)](https://www.w3.org/WAI/tutorials/page-structure/headings/)
+  #   <%= link_to_heading_practices %>
   class HeadingComponent < Primer::Component
     status :beta
 

app/components/primer/subhead_component.rb

@@ -1,16 +1,28 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use `Subhead` for page headings.
+  # Use `Subhead` as the start of a section. The `:heading` slot will render an `<h2>` font-sized text.
+  #
+  # - Optionally set the `:description` slot to render a short description and the `:actions` slot for a related action.
+  # - Use a succint, one-line description for the `:description` slot. For longer descriptions, omit the description slot and render a paragraph below the `Subhead`.
+  # - Use the actions slot to render a related action to the right of the heading. Use <%= link_to_component(Primer::ButtonComponent) %> or <%= link_to_component(Primer::LinkComponent) %>.
+  #
+  # @accessibility
+  #   The `:heading` slot defaults to rendering a `<div>`. Update the tag to a heading element with the appropriate level to improve page navigation for assistive technologies.
+  #   <%= link_to_heading_practices %>
   class SubheadComponent < Primer::Component
     status :beta
 
+    DEFAULT_HEADING_TAG = :div
+    HEADING_TAG_OPTIONS = [DEFAULT_HEADING_TAG, :h1, :h2, :h3, :h4, :h5, :h6].freeze
+
     # The heading
     #
+    # @param tag [Symbol] <%= one_of(Primer::SubheadComponent::HEADING_TAG_OPTIONS)%>
     # @param danger [Boolean] Whether to style the heading as dangerous.
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-    renders_one :heading, lambda { |danger: false, **system_arguments|
-      system_arguments[:tag] ||= :div
+    renders_one :heading, lambda { |tag: DEFAULT_HEADING_TAG, danger: false, **system_arguments|
+      system_arguments[:tag] = fetch_or_fallback(HEADING_TAG_OPTIONS, tag, DEFAULT_HEADING_TAG)
       system_arguments[:classes] = class_names(
         system_arguments[:classes],
         "Subhead-heading",
@@ -42,14 +54,32 @@ class SubheadComponent < Primer::Component
 
     # @example Default
     #   <%= render(Primer::SubheadComponent.new) do |component| %>
-    #     <% component.heading do %>
+    #     <% component.heading(tag: :h3) do %>
     #       My Heading
     #     <% end %>
     #     <% component.description do %>
     #       My Description
     #     <% end %>
     #   <% end %>
     #
+    # @example With dangerous heading
+    #   <%= render(Primer::SubheadComponent.new) do |component| %>
+    #     <% component.heading(tag: :h3, danger: true) do %>
+    #       My Heading
+    #     <% end %>
+    #     <% component.description do %>
+    #       My Description
+    #     <% end %>
+    #   <% end %>
+    #
+    # @example With long description
+    #   <%= render(Primer::SubheadComponent.new) do |component| %>
+    #     <% component.heading(tag: :h3) do %>
+    #       My Heading
+    #     <% end %>
+    #   <% end %>
+    #   <p> This is a longer description that is sitting below the Subhead. It's much longer than a description that could sit comfortably in the Subhead. </p>
+    #
     # @example Without border
     #   <%= render(Primer::SubheadComponent.new(hide_border: true)) do |component| %>
     #     <% component.heading do %>

docs/content/components/subhead.md

@@ -9,17 +9,26 @@ import Example from '../../src/@primer/gatsby-theme-doctocat/components/example'
 
 <!-- Warning: AUTO-GENERATED file, do not edit. Add code comments to your Ruby instead <3 -->
 
-Use `Subhead` for page headings.
+Use `Subhead` as the start of a section. The `:heading` slot will render an `<h2>` font-sized text.
+
+- Optionally set the `:description` slot to render a short description and the `:actions` slot for a related action.
+- Use a succint, one-line description for the `:description` slot. For longer descriptions, omit the description slot and render a paragraph below the `Subhead`.
+- Use the actions slot to render a related action to the right of the heading. Use [Button](/components/button) or [Link](/components/link).
+
+## Accessibility
+
+The `:heading` slot defaults to rendering a `<div>`. Update the tag to a heading element with the appropriate level to improve page navigation for assistive technologies.
+[Learn more about best heading practices (WAI Headings)](https://www.w3.org/WAI/tutorials/page-structure/headings/)
 
 ## Examples
 
 ### Default
 
-<Example src="<div class='Subhead hx_Subhead--responsive'>  <div class='Subhead-heading'>    My Heading</div>    <div class='Subhead-description'>    My Description</div></div>" />
+<Example src="<div class='Subhead hx_Subhead--responsive'>  <h3 class='Subhead-heading'>    My Heading</h3>    <div class='Subhead-description'>    My Description</div></div>" />
 
 ```erb
 <%= render(Primer::SubheadComponent.new) do |component| %>
-  <% component.heading do %>
+  <% component.heading(tag: :h3) do %>
     My Heading
   <% end %>
   <% component.description do %>
@@ -28,6 +37,34 @@ Use `Subhead` for page headings.
 <% end %>
 ```
 
+### With dangerous heading
+
+<Example src="<div class='Subhead hx_Subhead--responsive'>  <h3 class='Subhead-heading Subhead-heading--danger'>    My Heading</h3>    <div class='Subhead-description'>    My Description</div></div>" />
+
+```erb
+<%= render(Primer::SubheadComponent.new) do |component| %>
+  <% component.heading(tag: :h3, danger: true) do %>
+    My Heading
+  <% end %>
+  <% component.description do %>
+    My Description
+  <% end %>
+<% end %>
+```
+
+### With long description
+
+<Example src="<div class='Subhead hx_Subhead--responsive'>  <h3 class='Subhead-heading'>    My Heading</h3>    </div><p> This is a longer description that is sitting below the Subhead. It's much longer than a description that could sit comfortably in the Subhead. </p>" />
+
+```erb
+<%= render(Primer::SubheadComponent.new) do |component| %>
+  <% component.heading(tag: :h3) do %>
+    My Heading
+  <% end %>
+<% end %>
+<p> This is a longer description that is sitting below the Subhead. It's much longer than a description that could sit comfortably in the Subhead. </p>
+```
+
 ### Without border
 
 <Example src="<div class='Subhead hx_Subhead--responsive border-bottom-0 mb-0'>  <div class='Subhead-heading'>    My Heading</div>    <div class='Subhead-description'>    My Description</div></div>" />
@@ -81,6 +118,7 @@ The heading
 
 | Name | Type | Default | Description |
 | :- | :- | :- | :- |
+| `tag` | `Symbol` | N/A | One of `:div`, `:h1`, `:h2`, `:h3`, `:h4`, `:h5`, or `:h6`. |
 | `danger` | `Boolean` | N/A | Whether to style the heading as dangerous. |
 | `system_arguments` | `Hash` | N/A | [System arguments](/system-arguments) |
 

test/components/subhead_component_test.rb

@@ -19,6 +19,16 @@ def test_renders_heading
     assert_selector(".Subhead h2.Subhead-heading", text: "Hello World")
   end
 
+  def test_heading_tag_falls_back_to_default
+    without_fetch_or_fallback_raises do
+      render_inline(Primer::SubheadComponent.new) do |component|
+        component.heading(tag: :span) { "Hello World" }
+      end
+    end
+
+    assert_selector("div.Subhead-heading", text: "Hello World")
+  end
+
   def test_render_dangerous_heading
     render_inline(Primer::SubheadComponent.new) do |component|
       component.heading(danger: true) { "Hello World" }