move Primer::HeadingComponent to Primer::Beta::Heading

.changeset/violet-pigs-appear.md

@@ -0,0 +1,5 @@
+---
+'@primer/view-components': patch
+---
+
+migrating Primer::HeadingComponent to Primer::Beta::Heading, and replacing original with deprecated version

app/components/primer/base_component.rb

@@ -14,7 +14,7 @@ module Primer
   # For example:
   #
   # ```erb
-  # <%= render Primer::HeadingComponent.new(mt: [0, nil, nil, 4, 2]) do %>
+  # <%= render Primer::Beta::Heading.new(mt: [0, nil, nil, 4, 2]) do %>
   #   Hello world
   # <% end %>
   # ```

app/components/primer/beta/blankslate.rb

@@ -46,14 +46,14 @@ class Blankslate < Primer::Component
 
       # Required heading.
       #
-      # @param tag [String]  <%= one_of(Primer::HeadingComponent::TAG_OPTIONS) %>
+      # @param tag [String]  <%= one_of(Primer::Beta::Heading::TAG_OPTIONS) %>
       # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
       renders_one :heading, lambda { |tag:, **system_arguments|
         deny_tag_argument(**system_arguments)
         system_arguments[:tag] = tag
         system_arguments[:classes] = class_names("blankslate-heading", system_arguments[:classes])
 
-        Primer::HeadingComponent.new(**system_arguments)
+        Primer::Beta::Heading.new(**system_arguments)
       }
 
       # Optional description.

app/components/primer/beta/heading.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Primer
+  module Beta
+    # `Heading` should be used to communicate page organization and hierarchy.
+    #
+    # - Set tag to one of `:h1`, `:h2`, `:h3`, `:h4`, `:h5`, `:h6` based on what is appropriate for the page context.
+    # - Use `Heading` as the title of a section or sub section.
+    # - Do not use `Heading` for styling alone. For simply styling text, consider using <%= link_to_component(Primer::Beta::Text) %> with relevant <%= link_to_typography_docs %>
+    #   such as `font_size` and `font_weight`.
+    # - Do not jump heading levels. For instance, do not follow a `<h1>` with an `<h3>`. Heading levels should increase by one in ascending order.
+    #
+    # @accessibility
+    #   While sighted users rely on visual cues such as font size changes to determine what the heading is, assistive technology users rely on programatic cues that can be read out.
+    #   When text on a page is visually implied to be a heading, ensure that it is coded as a heading. Additionally, visually implied heading level and coded heading level should be
+    #   consistent. [See WCAG success criteria: 1.3.1: Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html)
+    #
+    #   Headings allow assistive technology users to quickly navigate around a page. Navigation to text that is not meant to be a heading can be a confusing experience.
+    #   <%= link_to_heading_practices %>
+    class Heading < Primer::Component
+      status :beta
+
+      TAG_FALLBACK = :h2
+      TAG_OPTIONS = [:h1, TAG_FALLBACK, :h3, :h4, :h5, :h6].freeze
+
+      # @example Default
+      #   <%= render(Primer::Beta::Heading.new(tag: :h1)) { "H1 Text" } %>
+      #   <%= render(Primer::Beta::Heading.new(tag: :h2)) { "H2 Text" } %>
+      #   <%= render(Primer::Beta::Heading.new(tag: :h3)) { "H3 Text" } %>
+      #   <%= render(Primer::Beta::Heading.new(tag: :h4)) { "H4 Text" } %>
+      #   <%= render(Primer::Beta::Heading.new(tag: :h5)) { "H5 Text" } %>
+      #   <%= render(Primer::Beta::Heading.new(tag: :h6)) { "H6 Text" } %>
+      #
+      # @param tag [String]  <%= one_of(Primer::Beta::Heading::TAG_OPTIONS) %>
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(tag:, **system_arguments)
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, TAG_FALLBACK)
+      end
+
+      def call
+        render(Primer::BaseComponent.new(**@system_arguments)) { content }
+      end
+    end
+  end
+end

app/components/primer/heading_component.rb

@@ -1,44 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # `Heading` should be used to communicate page organization and hierarchy.
-  #
-  # - Set tag to one of `:h1`, `:h2`, `:h3`, `:h4`, `:h5`, `:h6` based on what is appropriate for the page context.
-  # - Use `Heading` as the title of a section or sub section.
-  # - Do not use `Heading` for styling alone. For simply styling text, consider using <%= link_to_component(Primer::Beta::Text) %> with relevant <%= link_to_typography_docs %>
-  #   such as `font_size` and `font_weight`.
-  # - Do not jump heading levels. For instance, do not follow a `<h1>` with an `<h3>`. Heading levels should increase by one in ascending order.
-  #
-  # @accessibility
-  #   While sighted users rely on visual cues such as font size changes to determine what the heading is, assistive technology users rely on programatic cues that can be read out.
-  #   When text on a page is visually implied to be a heading, ensure that it is coded as a heading. Additionally, visually implied heading level and coded heading level should be
-  #   consistent. [See WCAG success criteria: 1.3.1: Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html)
-  #
-  #   Headings allow assistive technology users to quickly navigate around a page. Navigation to text that is not meant to be a heading can be a confusing experience.
-  #   <%= link_to_heading_practices %>
-  class HeadingComponent < Primer::Component
-    status :beta
-
-    TAG_FALLBACK = :h2
-    TAG_OPTIONS = [:h1, TAG_FALLBACK, :h3, :h4, :h5, :h6].freeze
-
-    # @example Default
-    #   <%= render(Primer::HeadingComponent.new(tag: :h1)) { "H1 Text" } %>
-    #   <%= render(Primer::HeadingComponent.new(tag: :h2)) { "H2 Text" } %>
-    #   <%= render(Primer::HeadingComponent.new(tag: :h3)) { "H3 Text" } %>
-    #   <%= render(Primer::HeadingComponent.new(tag: :h4)) { "H4 Text" } %>
-    #   <%= render(Primer::HeadingComponent.new(tag: :h5)) { "H5 Text" } %>
-    #   <%= render(Primer::HeadingComponent.new(tag: :h6)) { "H6 Text" } %>
-    #
-    # @param tag [String]  <%= one_of(Primer::HeadingComponent::TAG_OPTIONS) %>
-    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-    def initialize(tag:, **system_arguments)
-      @system_arguments = system_arguments
-      @system_arguments[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, TAG_FALLBACK)
-    end
-
-    def call
-      render(Primer::BaseComponent.new(**@system_arguments)) { content }
-    end
+  class HeadingComponent < Primer::Beta::Heading
+    status :deprecated
   end
 end

app/components/primer/popover_component.rb

@@ -27,13 +27,13 @@ class PopoverComponent < Primer::Component
 
     # The heading
     #
-    # @param tag [Symbol] (Primer::PopoverComponent::DEFAULT_HEADING_TAG) <%= one_of(Primer::HeadingComponent::TAG_OPTIONS) %>
+    # @param tag [Symbol] (Primer::PopoverComponent::DEFAULT_HEADING_TAG) <%= one_of(Primer::Beta::Heading::TAG_OPTIONS) %>
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
     renders_one :heading, lambda { |tag: DEFAULT_HEADING_TAG, **system_arguments|
       system_arguments[:tag] = tag
       system_arguments[:mb] ||= 2
 
-      Primer::HeadingComponent.new(**system_arguments)
+      Primer::Beta::Heading.new(**system_arguments)
     }
 
     # The body

app/lib/primer/view_helper.rb

@@ -8,7 +8,7 @@ class ViewHelperNotFound < StandardError; end
 
     HELPERS = {
       octicon: "Primer::OcticonComponent",
-      heading: "Primer::HeadingComponent",
+      heading: "Primer::Beta::Heading",
       time_ago: "Primer::TimeAgoComponent",
       image: "Primer::Image"
     }.freeze

docs/content/system-arguments.md

@@ -15,7 +15,7 @@ To apply different values across responsive breakpoints, pass an array with up t
 For example:
 
 ```erb
-<%= render Primer::HeadingComponent.new(mt: [0, nil, nil, 4, 2]) do %>
+<%= render Primer::Beta::Heading.new(mt: [0, nil, nil, 4, 2]) do %>
   Hello world
 <% end %>
 ```

docs/src/@primer/gatsby-theme-doctocat/nav.yml

@@ -56,7 +56,7 @@
   - title: FlexItem
     url: "/components/flexitem"
   - title: Heading
-    url: "/components/heading"
+    url: "/components/beta/heading"
   - title: HiddenTextExpander
     url: "/components/hiddentextexpander"
   - title: IconButton

lib/primer/view_components/linters/helpers/deprecated_components_helpers.rb

@@ -7,6 +7,7 @@ module Helpers
       module DeprecatedComponentsHelpers
         # If there is no alternative to suggest, set the value to nil
         COMPONENT_TO_USE_INSTEAD = {
+          "Primer::HeadingComponent" => "Primer::Beta::Heading",
           "Primer::ButtonGroup" => "Primer::Beta::ButtonGroup",
           "Primer::CloseButton" => "Primer::Beta::CloseButton",
           "Primer::CounterComponent" => "Primer::Beta::Counter",

lib/rubocop/cop/primer/component_name_migration.rb

@@ -16,6 +16,7 @@ module Primer
       class ComponentNameMigration < BaseCop
         DEPRECATIONS = {
           "Primer::DetailsComponent" => "Primer::Beta::Details",
+          "Primer::HeadingComponent" => "Primer::Beta::Heading",
           "Primer::BoxComponent" => "Primer::Box",
           "Primer::ButtonGroup" => "Primer::Beta::ButtonGroup",
           "Primer::CloseButton" => "Primer::Beta::CloseButton",

lib/tasks/docs.rake

@@ -58,7 +58,7 @@ namespace :docs do
       Primer::Beta::Flash,
       Primer::FlexComponent,
       Primer::FlexItemComponent,
-      Primer::HeadingComponent,
+      Primer::Beta::Heading,
       Primer::HiddenTextExpander,
       Primer::LabelComponent,
       Primer::LayoutComponent,

static/arguments.yml

@@ -565,6 +565,17 @@
     type: Hash
     default: N/A
     description: "[System arguments](/system-arguments)"
+- component: Heading
+  source: https://github.com/primer/view_components/tree/main/app/components/primer/beta/heading.rb
+  parameters:
+  - name: tag
+    type: String
+    default: N/A
+    description: One of `:h1`, `:h2`, `:h3`, `:h4`, `:h5`, or `:h6`.
+  - name: system_arguments
+    type: Hash
+    default: N/A
+    description: "[System arguments](/system-arguments)"
 - component: Text
   source: https://github.com/primer/view_components/tree/main/app/components/primer/beta/text.rb
   parameters:
@@ -727,17 +738,6 @@
     type: Hash
     default: N/A
     description: "[System arguments](/system-arguments)"
-- component: Heading
-  source: https://github.com/primer/view_components/tree/main/app/components/primer/heading_component.rb
-  parameters:
-  - name: tag
-    type: String
-    default: N/A
-    description: One of `:h1`, `:h2`, `:h3`, `:h4`, `:h5`, or `:h6`.
-  - name: system_arguments
-    type: Hash
-    default: N/A
-    description: "[System arguments](/system-arguments)"
 - component: HellipButton
   source: https://github.com/primer/view_components/tree/main/app/components/primer/hellip_button.rb
   parameters:

static/audited_at.json

@@ -27,6 +27,7 @@
   "Primer::Beta::Counter": "",
   "Primer::Beta::Details": "",
   "Primer::Beta::Flash": "",
+  "Primer::Beta::Heading": "",
   "Primer::Beta::Text": "",
   "Primer::Beta::Truncate": "",
   "Primer::Beta::Truncate::TruncateText": "",

static/constants.json

@@ -350,6 +350,17 @@
       "success": "flash-success"
     }
   },
+  "Primer::Beta::Heading": {
+    "TAG_FALLBACK": "h2",
+    "TAG_OPTIONS": [
+      "h1",
+      "h2",
+      "h3",
+      "h4",
+      "h5",
+      "h6"
+    ]
+  },
   "Primer::Beta::Text": {
     "DEFAULT_TAG": "span"
   },
@@ -523,15 +534,6 @@
     "FLEX_AUTO_DEFAULT": false
   },
   "Primer::HeadingComponent": {
-    "TAG_FALLBACK": "h2",
-    "TAG_OPTIONS": [
-      "h1",
-      "h2",
-      "h3",
-      "h4",
-      "h5",
-      "h6"
-    ]
   },
   "Primer::HellipButton": {
   },

static/statuses.json

@@ -27,6 +27,7 @@
   "Primer::Beta::Counter": "beta",
   "Primer::Beta::Details": "beta",
   "Primer::Beta::Flash": "beta",
+  "Primer::Beta::Heading": "beta",
   "Primer::Beta::Text": "beta",
   "Primer::Beta::Truncate": "beta",
   "Primer::Beta::Truncate::TruncateText": "alpha",
@@ -48,7 +49,7 @@
   "Primer::DropdownMenuComponent": "deprecated",
   "Primer::FlexComponent": "deprecated",
   "Primer::FlexItemComponent": "deprecated",
-  "Primer::HeadingComponent": "beta",
+  "Primer::HeadingComponent": "deprecated",
   "Primer::HellipButton": "alpha",
   "Primer::HiddenTextExpander": "alpha",
   "Primer::IconButton": "beta",

stories/primer/beta/heading_stories.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "primer/beta/heading"
+
+class Primer::Beta::HeadingStories < ViewComponent::Storybook::Stories
+  layout "storybook_preview"
+
+  story(:heading) do
+    controls do
+      select(:tag, Primer::Beta::Heading::TAG_OPTIONS, Primer::Beta::Heading::TAG_FALLBACK)
+    end
+
+    content do
+      "This is a heading!"
+    end
+  end
+end

test/components/heading_component_test.rb → test/components/beta/heading_test.rb

@@ -2,36 +2,36 @@
 
 require "test_helper"
 
-class PrimerHeadingComponentTest < Minitest::Test
+class PrimerBetaHeadingTest < Minitest::Test
   include Primer::ComponentTestHelpers
 
   def test_renders_content
-    render_inline(Primer::HeadingComponent.new(tag: :h1)) { "content" }
+    render_inline(Primer::Beta::Heading.new(tag: :h1)) { "content" }
 
     assert_text("content")
   end
 
   def test_falls_back_when_tag_isnt_valid
     without_fetch_or_fallback_raises do
-      render_inline(Primer::HeadingComponent.new(tag: :div)) { "content" }
+      render_inline(Primer::Beta::Heading.new(tag: :div)) { "content" }
 
       assert_selector("h2")
     end
   end
 
   def test_renders_h1
-    render_inline(Primer::HeadingComponent.new(tag: :h1)) { "content" }
+    render_inline(Primer::Beta::Heading.new(tag: :h1)) { "content" }
 
     assert_selector("h1")
   end
 
   def test_renders_h3
-    render_inline(Primer::HeadingComponent.new(tag: :h3)) { "content" }
+    render_inline(Primer::Beta::Heading.new(tag: :h3)) { "content" }
 
     assert_selector("h3")
   end
 
   def test_status
-    assert_component_state(Primer::HeadingComponent, :beta)
+    assert_component_state(Primer::Beta::Heading, :beta)
   end
 end

test/components/component_test.rb

@@ -59,7 +59,7 @@ class PrimerComponentTest < Minitest::Test
     [Primer::FlexComponent, {}],
     [Primer::Beta::Flash, {}],
     [Primer::FlexItemComponent, { flex_auto: true }],
-    [Primer::HeadingComponent, { tag: :h1 }],
+    [Primer::Beta::Heading, { tag: :h1 }],
     [Primer::HiddenTextExpander, { "aria-label": "No action" }],
     [Primer::LabelComponent, {}],
     [Primer::LayoutComponent, {}],
@@ -87,6 +87,7 @@ class PrimerComponentTest < Minitest::Test
 
   def test_registered_components
     ignored_components = [
+      "Primer::HeadingComponent",
       "Primer::ButtonGroup",
       "Primer::CloseButton",
       "Primer::CounterComponent",