primer_view_components 0.1.0 → 0.1.1

data/app/components/primer/alpha/action_list/divider.rb

@@ -3,7 +3,7 @@
 module Primer
   module Alpha
     class ActionList
-      # Section heading rendered above the section contents.
+      # Group heading rendered above the group contents.
       class Divider < Primer::Component
         DEFAULT_SCHEME = :subtle
         SCHEME_MAPPINGS = {
@@ -16,7 +16,7 @@ module Primer
         # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
         def initialize(scheme: DEFAULT_SCHEME, **system_arguments)
           @system_arguments = system_arguments
-          @system_arguments[:tag] = :li
+          @system_arguments[:tag] = :div
           @system_arguments[:role] = :separator
           @system_arguments[:'aria-hidden'] = true
           @scheme = fetch_or_fallback(SCHEME_OPTIONS, scheme, DEFAULT_SCHEME)

data/app/components/primer/alpha/action_list/heading.html.erb

@@ -1,4 +1,4 @@
-<%= render(Primer::BaseComponent.new(**@system_arguments)) do %>
+<%= render(Primer::BaseComponent.new(tag: :div, **@system_arguments)) do %>
   <%= render(Primer::BaseComponent.new(tag: @tag, classes: "ActionList-sectionDivider-title", id: @list_id)) do %>
     <%= @title %>
   <% end %>

data/app/components/primer/alpha/action_list/heading.rb

@@ -11,21 +11,27 @@ module Primer
           :filled => "ActionList-sectionDivider--filled"
         }.freeze
         SCHEME_OPTIONS = SCHEME_MAPPINGS.keys.freeze
+        HEADING_MIN = 1
+        HEADING_MAX = 6
+        HEADING_LEVELS = (HEADING_MIN..HEADING_MAX).to_a.freeze
 
         # @param list_id [String] The unique identifier of the sub list the heading belongs to. Used internally.
         # @param title [String] Sub list title.
+        # @param heading_level [Integer] Heading level. Level 2 results in an `<h2>` tag, level 3 an `<h3>` tag, etc.
         # @param subtitle [String] Optional sub list description.
         # @param scheme [Symbol] Display a background color if scheme is `filled`.
-        # @param tag [Symbol] Semantic tag for the heading.
+        # @param tag [Integer] Semantic tag for the heading.
         # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-        def initialize(list_id:, title:, tag: :h3, scheme: DEFAULT_SCHEME, subtitle: nil, **system_arguments)
-          @tag = tag
+        def initialize(list_id:, title:, heading_level: 3, scheme: DEFAULT_SCHEME, subtitle: nil, **system_arguments)
+          raise "Heading level must be between #{HEADING_MIN} and #{HEADING_MAX}" unless HEADING_LEVELS.include?(heading_level)
+
+          @heading_level = heading_level
+          @tag = :"h#{heading_level}"
           @system_arguments = system_arguments
           @list_id = list_id
           @title = title
           @subtitle = subtitle
           @scheme = fetch_or_fallback(SCHEME_OPTIONS, scheme, DEFAULT_SCHEME)
-          @system_arguments[:tag] = :li
           @system_arguments[:classes] = class_names(
             "ActionList-sectionDivider",
             SCHEME_MAPPINGS[@scheme],

data/app/components/primer/alpha/action_list/item.rb

@@ -112,7 +112,7 @@ module Primer
         # @private
         renders_one :private_content
 
-        attr_reader :list, :href, :active, :disabled, :parent
+        attr_reader :id, :list, :href, :active, :disabled, :parent
 
         # Whether or not this item is active.
         #
@@ -150,7 +150,7 @@ module Primer
           parent: nil,
           truncate_label: false,
           href: nil,
-          role: :listitem,
+          role: nil,
           size: DEFAULT_SIZE,
           scheme: DEFAULT_SCHEME,
           disabled: false,
@@ -184,7 +184,7 @@ module Primer
             "ActionListItem"
           )
 
-          @system_arguments[:role] = role
+          @system_arguments[:role] = role if role
 
           @system_arguments[:aria] ||= {}
           @system_arguments[:aria][:disabled] = "true" if @disabled

data/app/components/primer/alpha/action_list.html.erb

@@ -1,15 +1,13 @@
-<%= render(Primer::BaseComponent.new(tag: :ul, role: @role, classes: "ActionListWrap")) do %>
+<%= render(Primer::BaseComponent.new(tag: :div)) do %>
   <% if heading %>
     <%= heading %>
   <% end %>
-  <%= render(Primer::BaseComponent.new(tag: :li, **@list_wrapper_arguments)) do %>
-    <%= render(Primer::BaseComponent.new(tag: :ul, **@system_arguments)) do %>
-      <% items.each_with_index do |item, index| %>
-        <% if index > 0 && @show_dividers %>
-          <%= render(Primer::Alpha::ActionList::Divider.new) %>
-        <% end %>
-        <%= item %>
+  <%= render(Primer::BaseComponent.new(tag: :ul, **@system_arguments)) do %>
+    <% items.each_with_index do |item, index| %>
+      <% if index > 0 && @show_dividers %>
+        <%= render(Primer::Alpha::ActionList::Divider.new) %>
       <% end %>
+      <%= item %>
     <% end %>
   <% end %>
 <% end %>

data/app/components/primer/alpha/action_list.rb

@@ -61,10 +61,10 @@ module Primer
         **system_arguments
       )
         @id = self.class.generate_id
-        @role = role
 
         @system_arguments = system_arguments
         @system_arguments[:tag] = :ul
+        @system_arguments[:role] = role
         @item_classes = item_classes
         @scheme = fetch_or_fallback(SCHEME_OPTIONS, scheme, DEFAULT_SCHEME)
         @show_dividers = show_dividers
@@ -72,7 +72,6 @@ module Primer
           SCHEME_MAPPINGS[@scheme],
           system_arguments[:classes],
           "ActionListWrap",
-          "ActionListWrap--subGroup",
           "ActionListWrap--divided" => @show_dividers
         )
 
@@ -81,18 +80,14 @@ module Primer
 
       # @private
       def before_render
+        aria_label = aria(:label, @system_arguments)
+
         if heading.present?
           @system_arguments[:"aria-labelledby"] = @id
-        elsif aria(:label, @system_arguments).blank?
+          raise ArgumentError, "An aria-label should not be provided if a heading is present" if aria_label.present?
+        elsif aria_label.blank?
           raise ArgumentError, "An aria-label or heading must be provided"
         end
-
-        return if items.blank?
-
-        @list_wrapper_arguments[:classes] = class_names(
-          @list_wrapper_arguments[:classes],
-          "ActionListItem--hasSubItem"
-        )
       end
 
       # @private

data/app/components/primer/alpha/nav_list/{section.rb → group.rb}

@@ -6,10 +6,10 @@ module Primer
       # A logical grouping of navigation links with an optional heading.
       #
       # See <%= link_to_component(Primer::Alpha::NavList) %> for usage examples.
-      class Section < ActionList
-        # A special "show more" list item that appears at the bottom of the section. Clicking
+      class Group < ActionList
+        # A special "show more" list item that appears at the bottom of the group. Clicking
         # the item will fetch the next page of results from the URL passed in the `src` argument
-        # and append the resulting chunk of HTML to the section.
+        # and append the resulting chunk of HTML to the group.
         #
         # @param src [String] The URL to query for additional pages of list items.
         # @param pages [Integer] The total number of pages in the result set.
@@ -51,14 +51,14 @@ module Primer
           super(**@system_arguments)
         end
 
-        # Cause this section to show its list of sub items when rendered.
+        # Cause this group to show its list of sub items when rendered.
         # :nocov:
         def expand!
           @expanded = true
         end
         # :nocov:
 
-        # The items contained within this section.
+        # The items contained within this group.
         #
         # @return [Array<Primer::Alpha::ActionList::Item>]
         def items

data/app/components/primer/alpha/nav_list/item.html.erb

@@ -1,7 +1,7 @@
 <% with_private_content do %>
   <% unless items.empty? %>
     <% capture do %>
-      <%= render(Primer::BaseComponent.new(tag: :ul, **@sub_list_arguments)) do %>
+      <%= render(Primer::BaseComponent.new(tag: :ul, role: :list, **@sub_list_arguments)) do %>
         <% items.each do |item| %>
           <%= item %>
         <% end %>

data/app/components/primer/alpha/nav_list/item.rb

@@ -47,6 +47,10 @@ module Primer
             )
           }
 
+          @list = system_arguments[:list]
+
+          @sub_list_arguments["data-action"] = "keydown:#{@list.custom_element_name}#handleItemWithSubItemKeydown" if @list
+
           overrides = { "data-item-id": @selected_by_ids.join(" ") }
 
           super(**system_arguments, **overrides)
@@ -79,9 +83,19 @@ module Primer
 
           return if items.blank?
 
+          @sub_list_arguments[:aria] = merge_aria(
+            @sub_list_arguments,
+            { aria: { labelledby: id } }
+          )
+
+          raise ArgumentError, "Items with sub-items cannot have hrefs" if href.present?
+
           @content_arguments[:tag] = :button
           @content_arguments[:"aria-expanded"] = @expanded.to_s
-          @content_arguments[:"data-action"] = "click:#{@list.custom_element_name}#handleItemWithSubItemClick"
+          @content_arguments[:"data-action"] = "
+            click:#{@list.custom_element_name}#handleItemWithSubItemClick
+            keydown:#{@list.custom_element_name}#handleItemWithSubItemKeydown
+          "
 
           with_private_trailing_action_icon(:"chevron-down", classes: "ActionListItem-collapseIcon")
 

data/app/components/primer/alpha/nav_list.d.ts

@@ -18,6 +18,7 @@ export declare class NavListElement extends HTMLElement {
     collapseItem(item: HTMLElement): void;
     itemIsExpanded(item: HTMLElement | null): boolean;
     handleItemWithSubItemClick(e: Event): void;
+    handleItemWithSubItemKeydown(e: KeyboardEvent): void;
     private showMore;
     private setShowMoreItemState;
 }

data/app/components/primer/alpha/nav_list.html.erb

@@ -1,10 +1,10 @@
-<%= render(Primer::BaseComponent.new(tag: :ul, **@system_arguments)) do %>
-  <% sections.each_with_index do |section, index| %>
-    <% if index > 0 %>
-      <%= render(Primer::Alpha::ActionList::Divider.new) %>
+<%= render(Primer::BaseComponent.new(tag: :nav, **@system_arguments)) do %>
+  <nav-list>
+    <% groups.each_with_index do |group, index| %>
+      <% if index > 0 %>
+        <%= render(Primer::Alpha::ActionList::Divider.new) %>
+      <% end %>
+      <%= group %>
     <% end %>
-    <li>
-      <%= section %>
-    </li>
-  <% end %>
+  </nav-list>
 <% end %>

data/app/components/primer/alpha/nav_list.js

@@ -82,6 +82,7 @@ let NavListElement = class NavListElement extends HTMLElement {
         var _a;
         (_a = item.nextElementSibling) === null || _a === void 0 ? void 0 : _a.setAttribute('data-hidden', '');
         item.setAttribute('aria-expanded', 'false');
+        item.focus();
     }
     itemIsExpanded(item) {
         if ((item === null || item === void 0 ? void 0 : item.tagName) === 'A') {
@@ -105,6 +106,26 @@ let NavListElement = class NavListElement extends HTMLElement {
         }
         e.stopPropagation();
     }
+    // collapse item
+    handleItemWithSubItemKeydown(e) {
+        const el = e.currentTarget;
+        if (!(el instanceof HTMLElement))
+            return;
+        let button = el.closest('button');
+        if (!button) {
+            const button_id = el.getAttribute('aria-labelledby');
+            if (button_id) {
+                button = document.getElementById(button_id);
+            }
+            else {
+                return;
+            }
+        }
+        if (this.itemIsExpanded(button) && e.key === 'Escape') {
+            this.collapseItem(button);
+        }
+        e.stopPropagation();
+    }
     async showMore(e) {
         var _a, _b;
         e.preventDefault();

data/app/components/primer/alpha/nav_list.rb

@@ -3,13 +3,13 @@
 module Primer
   module Alpha
     # `NavList` provides a simple way to render side navigation, i.e. navigation
-    # that appears to the left or right side of some main content. Each section in a
+    # that appears to the left or right side of some main content. Each group in a
     # nav list is a list of links.
     #
-    # Nav list sections can contain sub items. Rather than navigating to a URL, sections
+    # Nav list groups can contain sub items. Rather than navigating to a URL, groups
     # with sub items expand and collapse on click. To indicate this functionality, the
-    # section will automatically render with a trailing chevron icon that changes direction
-    # when the section expands and collapses.
+    # group will automatically render with a trailing chevron icon that changes direction
+    # when the group expands and collapses.
     #
     # Nav list items appear visually active when selected. Each nav item must have one
     # or more ID values that determine which item will appear selected. Use the
@@ -22,40 +22,40 @@ module Primer
         "nav-list"
       end
 
-      # Sections. Each section is a list of links and an optional heading.
+      # Groups. Each group is a list of links and an optional heading.
       #
-      # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::NavList::Section) %>.
-      renders_many :sections, lambda { |**system_arguments|
-        Primer::Alpha::NavList::Section.new(selected_item_id: @selected_item_id, **system_arguments)
+      # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::NavList::Group) %>.
+      renders_many :groups, lambda { |**system_arguments|
+        Primer::Alpha::NavList::Group.new(selected_item_id: @selected_item_id, **system_arguments)
       }
 
       # @example Items and headings
       #
       #   <%= render(Primer::Alpha::NavList.new(selected_item_id: :personal_info)) do |component| %>
-      #     <% component.with_section(aria: { label: "Settings" }) do |section| %>
-      #       <% section.with_item(label: "General", selected_by_ids: :general, href: "/settings/general") %>
+      #     <% component.with_group(aria: { label: "Settings" }) do |group| %>
+      #       <% group.with_item(label: "General", selected_by_ids: :general, href: "/settings/general") %>
       #     <% end %>
-      #     <% component.with_section(aria: { label: "Account settings" }) do |section| %>
-      #       <% section.with_heading(title: "Account Settings") %>
-      #       <% section.with_item(label: "Personal Information", selected_by_ids: :personal_info, href: "/account/info") %>
-      #       <% section.with_item(label: "Password", selected_by_ids: :password, href: "/account/password") %>
-      #       <% section.with_item(label: "Billing info", selected_by_ids: :billing, href: "/account/billing") %>
+      #     <% component.with_group do |group| %>
+      #       <% group.with_heading(title: "Account Settings") %>
+      #       <% group.with_item(label: "Personal Information", selected_by_ids: :personal_info, href: "/account/info") %>
+      #       <% group.with_item(label: "Password", selected_by_ids: :password, href: "/account/password") %>
+      #       <% group.with_item(label: "Billing info", selected_by_ids: :billing, href: "/account/billing") %>
       #     <% end %>
       #   <% end %>
       #
       # @example Leading and trailing visuals
       #
       #   <%= render(Primer::Alpha::NavList.new(selected_item_id: :personal_info)) do |component| %>
-      #     <% component.with_section(aria: { label: "Account settings" }) do |section| %>
-      #       <% section.with_heading(title: "Account Settings") %>
-      #       <% section.with_item(label: "Personal Information", selected_by_ids: :personal_info, href: "/account/info") do |item| %>
+      #     <% component.with_group do |group| %>
+      #       <% group.with_heading(title: "Account Settings") %>
+      #       <% group.with_item(label: "Personal Information", selected_by_ids: :personal_info, href: "/account/info") do |item| %>
       #         <% item.with_leading_visual_avatar(src: "https://github.com/github.png", alt: "GitHub") %>
       #       <% end %>
-      #       <% section.with_item(label: "Notifications", selected_by_ids: :notifications, href: "/account/notifications") do |item| %>
+      #       <% group.with_item(label: "Notifications", selected_by_ids: :notifications, href: "/account/notifications") do |item| %>
       #         <% item.with_leading_visual_icon(icon: :bell) %>
       #         <% item.with_trailing_visual_counter(count: 15) %>
       #       <% end %>
-      #       <% section.with_item(label: "Billing info", selected_by_ids: :billing, href: "/account/billing") do |item| %>
+      #       <% group.with_item(label: "Billing info", selected_by_ids: :billing, href: "/account/billing") do |item| %>
       #         <% item.with_leading_visual_icon(icon: :package) %>
       #         <% item.with_trailing_visual_icon(icon: :"dot-fill", color: :attention) %>
       #       <% end %>
@@ -65,9 +65,9 @@ module Primer
       # @example Expandable sub items
       #
       #   <%= render(Primer::Alpha::NavList.new(selected_item_id: :email_notifications)) do |component| %>
-      #     <% component.with_section(aria: { label: "Account settings" }) do |section| %>
-      #       <% section.with_heading(title: "Account Settings") %>
-      #       <% section.with_item(label: "Notification settings") do |item| %>
+      #     <% component.with_group do |group| %>
+      #       <% group.with_heading(title: "Account Settings") %>
+      #       <% group.with_item(label: "Notification settings") do |item| %>
       #         <% item.with_leading_visual_icon(icon: :bell) %>
       #         <% item.with_item(label: "Email", selected_by_ids: :email_notifications, href: "/account/notifications/email") do |subitem| %>
       #           <% subitem.with_trailing_visual_icon(icon: :mail) %>
@@ -76,7 +76,7 @@ module Primer
       #           <% subitem.with_trailing_visual_icon(icon: :"device-mobile") %>
       #         <% end %>
       #       <% end %>
-      #       <% section.with_item(label: "Messages") do |item| %>
+      #       <% group.with_item(label: "Messages") do |item| %>
       #         <% item.with_leading_visual_icon(icon: :bookmark) %>
       #         <% item.with_item(label: "Inbox", href: "/account/messages/inbox") do |subitem| %>
       #           <% subitem.with_trailing_visual_counter(count: 10) %>
@@ -91,12 +91,12 @@ module Primer
       # @example Trailing action
       #
       #   <%= render(Primer::Alpha::NavList.new) do |component| %>
-      #     <% component.with_section(aria: { label: "Favorite foods" }) do |section| %>
-      #       <% section.with_heading(title: "My Favorite Foods") %>
-      #       <% section.with_item(label: "Popplers", selected_by_ids: :popplers, href: "/foods/popplers") do |item| %>
+      #     <% component.with_group do |group| %>
+      #       <% group.with_heading(title: "My Favorite Foods") %>
+      #       <% group.with_item(label: "Popplers", selected_by_ids: :popplers, href: "/foods/popplers") do |item| %>
       #         <% item.with_trailing_action(show_on_hover: false, icon: "plus", "aria-label": "Add new food", size: :medium) %>
       #       <% end %>
-      #       <% section.with_item(label: "Slurm", selected_by_ids: :slurm, href: "/foods/slurm") do |item| %>
+      #       <% group.with_item(label: "Slurm", selected_by_ids: :slurm, href: "/foods/slurm") do |item| %>
       #         <% item.with_trailing_action(show_on_hover: true, icon: "plus", "aria-label": "Add new food", size: :medium) %>
       #       <% end %>
       #     <% end %>
@@ -106,10 +106,6 @@ module Primer
       # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
       def initialize(selected_item_id: nil, **system_arguments)
         @system_arguments = system_arguments
-        @system_arguments[:classes] = class_names(
-          @system_arguments[:classes],
-          "ActionListWrap"
-        )
         @selected_item_id = selected_item_id
       end
     end

data/app/components/primer/alpha/nav_list.ts

@@ -87,6 +87,7 @@ export class NavListElement extends HTMLElement {
   collapseItem(item: HTMLElement) {
     item.nextElementSibling?.setAttribute('data-hidden', '')
     item.setAttribute('aria-expanded', 'false')
+    item.focus()
   }
 
   itemIsExpanded(item: HTMLElement | null) {
@@ -112,6 +113,28 @@ export class NavListElement extends HTMLElement {
     e.stopPropagation()
   }
 
+  // collapse item
+  handleItemWithSubItemKeydown(e: KeyboardEvent) {
+    const el = e.currentTarget
+    if (!(el instanceof HTMLElement)) return
+
+    let button = el.closest<HTMLButtonElement>('button')
+    if (!button) {
+      const button_id = el.getAttribute('aria-labelledby')
+      if (button_id) {
+        button = document.getElementById(button_id) as HTMLButtonElement
+      } else {
+        return
+      }
+    }
+
+    if (this.itemIsExpanded(button) && e.key === 'Escape') {
+      this.collapseItem(button)
+    }
+
+    e.stopPropagation()
+  }
+
   private async showMore(e: Event) {
     e.preventDefault()
     if (this.showMoreDisabled) return

data/app/components/primer/alpha/navigation/tab.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    module Navigation
+      # This component is part of navigation components such as `Primer::Alpha::TabNav`
+      # and `Primer::Alpha::UnderlineNav` and should not be used by itself.
+      #
+      # @accessibility
+      #   `Tab` renders the selected anchor tab with `aria-current="page"` by default.
+      #    When the selected tab does not correspond to the current page, such as in a nested inner tab, make sure to use aria-current="true"
+      class Tab < Primer::Component
+        status :alpha
+
+        DEFAULT_ARIA_CURRENT_FOR_ANCHOR = :page
+        ARIA_CURRENT_OPTIONS_FOR_ANCHOR = [true, DEFAULT_ARIA_CURRENT_FOR_ANCHOR].freeze
+        # Panel controlled by the Tab. This will not render anything in the tab itself.
+        # It will provide a accessor for the Tab's parent to call and render the panel
+        # content in the appropriate place.
+        # Refer to `UnderlineNav` and `TabNav` implementations for examples.
+        #
+        # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+        renders_one :panel, lambda { |**system_arguments|
+          return unless @with_panel
+
+          deny_tag_argument(**system_arguments)
+          system_arguments[:id] = @panel_id
+          system_arguments[:tag] = :div
+          system_arguments[:role] ||= :tabpanel
+          system_arguments[:tabindex] = 0
+          system_arguments[:hidden] = true unless @selected
+
+          label_present = aria("label", system_arguments) || aria("labelledby", system_arguments)
+          unless label_present
+            if @id.present?
+              system_arguments[:"aria-labelledby"] = @id
+            elsif !Rails.env.production?
+              raise ArgumentError, "Panels must be labelled. Either set a unique `id` on the tab, or set an `aria-label` directly on the panel"
+            end
+          end
+
+          Primer::BaseComponent.new(**system_arguments)
+        }
+
+        # Icon to be rendered in the Tab left.
+        #
+        # @param kwargs [Hash] The same arguments as <%= link_to_component(Primer::Beta::Octicon) %>.
+        renders_one :icon, lambda { |icon = nil, **system_arguments|
+          system_arguments[:classes] = class_names(
+            @icon_classes,
+            system_arguments[:classes]
+          )
+          Primer::Beta::Octicon.new(icon, **system_arguments)
+        }
+
+        # The Tab's text.
+        #
+        # @param kwargs [Hash] The same arguments as <%= link_to_component(Primer::Beta::Text) %>.
+        renders_one :text, Primer::Beta::Text
+
+        # Counter to be rendered in the Tab right.
+        #
+        # @param kwargs [Hash] The same arguments as <%= link_to_component(Primer::Beta::Counter) %>.
+        renders_one :counter, Primer::Beta::Counter
+
+        attr_reader :selected
+
+        # @example Default
+        #   <%= render(Primer::Alpha::Navigation::Tab.new(selected: true)) do |component| %>
+        #     <% component.with_text { "Selected" } %>
+        #   <% end %>
+        #   <%= render(Primer::Alpha::Navigation::Tab.new) do |component| %>
+        #     <% component.with_text { "Not selected" } %>
+        #   <% end %>
+        #
+        # @example With icons and counters
+        #   <%= render(Primer::Alpha::Navigation::Tab.new) do |component| %>
+        #     <% component.with_icon(:star) %>
+        #     <% component.with_text { "Tab" } %>
+        #   <% end %>
+        #   <%= render(Primer::Alpha::Navigation::Tab.new) do |component| %>
+        #     <% component.with_icon(:star) %>
+        #     <% component.with_text { "Tab" } %>
+        #     <% component.with_counter(count: 10) %>
+        #   <% end %>
+        #   <%= render(Primer::Alpha::Navigation::Tab.new) do |component| %>
+        #     <% component.with_text { "Tab" } %>
+        #     <% component.with_counter(count: 10) %>
+        #   <% end %>
+        #
+        # @example Inside a list
+        #   <%= render(Primer::Alpha::Navigation::Tab.new(list: true)) do |component| %>
+        #     <% component.with_text { "Tab" } %>
+        #   <% end %>
+        #
+        # @example With custom HTML
+        #   <%= render(Primer::Alpha::Navigation::Tab.new) do %>
+        #     <div>
+        #       This is my <strong>custom HTML</strong>
+        #     </div>
+        #   <% end %>
+        #
+        # @param list [Boolean] Whether the Tab is an item in a `<ul>` list.
+        # @param selected [Boolean] Whether the Tab is selected or not.
+        # @param with_panel [Boolean] Whether the Tab has an associated panel.
+        # @param panel_id [String] Only applies if `with_panel` is `true`. Unique id of panel.
+        # @param icon_classes [Boolean] Classes that must always be applied to icons.
+        # @param wrapper_arguments [Hash] <%= link_to_system_arguments_docs %> to be used in the `<li>` wrapper when the tab is an item in a list.
+        # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+        def initialize(list: false, selected: false, with_panel: false, panel_id: "", icon_classes: "", wrapper_arguments: {}, **system_arguments)
+          @selected = selected
+          @icon_classes = icon_classes
+          @list = list
+          @with_panel = with_panel
+
+          @system_arguments = system_arguments
+          @id = @system_arguments[:id]
+          @wrapper_arguments = wrapper_arguments
+
+          if with_panel || @system_arguments[:tag] == :button
+            @system_arguments[:tag] = :button
+            @system_arguments[:type] = :button
+            @system_arguments[:role] = :tab
+            panel_id(panel_id)
+            # https://www.w3.org/TR/wai-aria-practices/#presentation_role
+            @wrapper_arguments[:role] = :presentation
+          else
+            @system_arguments[:tag] = :a
+          end
+
+          @wrapper_arguments[:tag] = :li
+          @wrapper_arguments[:display] ||= :inline_flex
+
+          return unless @selected
+
+          if @system_arguments[:tag] == :a
+            aria_current = aria("current", system_arguments) || DEFAULT_ARIA_CURRENT_FOR_ANCHOR
+            @system_arguments[:"aria-current"] = fetch_or_fallback(ARIA_CURRENT_OPTIONS_FOR_ANCHOR, aria_current, DEFAULT_ARIA_CURRENT_FOR_ANCHOR)
+          else
+            @system_arguments[:"aria-selected"] = true
+          end
+        end
+
+        def wrapper
+          unless @list
+            yield
+            return # returning `yield` caused a double render
+          end
+
+          render(Primer::BaseComponent.new(**@wrapper_arguments)) do
+            yield if block_given?
+          end
+        end
+
+        private
+
+        def panel_id(panel_id)
+          if panel_id.blank?
+            raise ArgumentError, "`panel_id` is required" unless Rails.env.production?
+          else
+            @panel_id = panel_id
+            @system_arguments[:"aria-controls"] = @panel_id
+          end
+        end
+      end
+    end
+  end
+end