primer_view_components 0.0.96 → 0.0.97

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

@@ -0,0 +1,39 @@
+<%= render(Primer::BaseComponent.new(tag: :li, **@system_arguments)) do %>
+  <%= render(Primer::BaseComponent.new(**@content_arguments)) do %>
+    <% if private_leading_action_icon %>
+      <span class="ActionListItem-visual ActionListItem-action--leading">
+        <%= private_leading_action_icon %>
+      </span>
+    <% end %>
+    <% if leading_visual %>
+      <span class="ActionListItem-visual ActionListItem-visual--leading">
+        <%= leading_visual %>
+      </span>
+    <% end %>
+    <%= render(Primer::ConditionalWrapper.new(condition: description?, tag: :span, **@description_wrapper_arguments)) do %>
+      <%= render(Primer::BaseComponent.new(tag: :span, **@label_arguments)) do %>
+        <%= @label %>
+      <% end %>
+      <% if description? %>
+        <span class="ActionListItem-description">
+          <%= description %>
+        </span>
+      <% end %>
+    <% end %>
+    <% if trailing_visual %>
+      <span class="ActionListItem-visual ActionListItem-visual--trailing">
+        <%= trailing_visual %>
+      </span>
+    <% end %>
+    <% if private_trailing_action_icon %>
+      <span class="ActionListItem-visual ActionListItem-action--trailing">
+        <%= private_trailing_action_icon %>
+      </span>
+    <% end %>
+  <% end %>
+  <%= tooltip %>
+  <% if trailing_action %>
+    <%= trailing_action %>
+  <% end %>
+  <%= private_content %>
+<% end %>

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

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    class ActionList
+      # An individual `ActionList` item. Items can optionally include leading and/or trailing visuals,
+      # such as icons, avatars, and counters.
+      class Item < Primer::Component
+        DEFAULT_SIZE = :medium
+        SIZE_MAPPINGS = {
+          DEFAULT_SIZE => nil,
+          :large => "ActionListContent--sizeLarge",
+          :xlarge => "ActionListContent--sizeXLarge"
+        }.freeze
+        SIZE_OPTIONS = SIZE_MAPPINGS.keys.freeze
+
+        DEFAULT_DESCRIPTION_SCHEME = :block
+        DESCRIPTION_SCHEME_MAPPINGS = {
+          :inline => "ActionListItem-descriptionWrap--inline",
+          DEFAULT_DESCRIPTION_SCHEME => "ActionListItem-descriptionWrap"
+        }.freeze
+        DESCRIPTION_SCHEME_OPTIONS = DESCRIPTION_SCHEME_MAPPINGS.keys.freeze
+
+        DEFAULT_SCHEME = :default
+        SCHEME_MAPPINGS = {
+          DEFAULT_SCHEME => nil,
+          :danger => "ActionListItem--danger"
+        }.freeze
+        SCHEME_OPTIONS = SCHEME_MAPPINGS.keys.freeze
+
+        # Description content that complements the item's label. See `ActionList`'s `description_scheme` argument
+        # for layout options.
+        renders_one :description
+
+        # An icon or avatar that will render to the left of the label.
+        #
+        # To render an icon, call the `with_leading_visual_icon` method, which accepts the arguments accepted by <%= link_to_component(Primer::OcticonComponent) %>.
+        #
+        # To render an avatar, call the `with_leading_visual_avatar` method, which accepts the arguments accepted by <%= link_to_component(Primer::Beta::Avatar) %>.
+        renders_one :leading_visual, types: {
+          icon: Primer::OcticonComponent,
+          avatar: ->(**kwargs) { Primer::Beta::Avatar.new(**{ **kwargs, size: 16 }) }
+        }
+
+        # Used internally.
+        #
+        # @private
+        renders_one :private_leading_action_icon, Primer::OcticonComponent
+
+        # An icon, label, counter, or text to render to the right of the label.
+        #
+        # To render an icon, call the `with_leading_visual_icon` method, which accepts the arguments accepted by <%= link_to_component(Primer::OcticonComponent) %>.
+        #
+        # To render a label, call the `with_leading_visual_label` method, which accepts the arguments accepted by <%= link_to_component(Primer::LabelComponent) %>.
+        #
+        # To render a counter, call the `with_leading_visual_counter` method, which accepts the arguments accepted by <%= link_to_component(Primer::CounterComponent) %>.
+        #
+        # To render text, call the `with_leading_visual_text` method and pass a block that returns a string. Eg:
+        # ```ruby
+        # with_leading_visual_text { "Text here" }`
+        # ```
+        renders_one :trailing_visual, types: {
+          icon: Primer::OcticonComponent,
+          label: Primer::LabelComponent,
+          counter: Primer::CounterComponent,
+          text: ->(text) { text }
+        }
+
+        # Used internally.
+        #
+        # @private
+        renders_one :private_trailing_action_icon, Primer::OcticonComponent
+
+        # A button rendered after the trailing icon that can be used to show a menu, activate
+        # a dialog, etc.
+        #
+        # @param show_on_hover [Boolean] Whether or not to show the button when the list item is hovered. If `true`, the button will be invisible until hovered. If `false`, the button will always be visible. Defaults to `false`.
+        # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Beta::IconButton) %>.
+        renders_one :trailing_action, lambda { |show_on_hover: false, **system_arguments|
+          @trailing_action_on_hover = show_on_hover
+
+          Primer::Beta::IconButton.new(scheme: :invisible, classes: ["ActionListItem-trailingAction"], **system_arguments)
+        }
+
+        # `Tooltip` that appears on mouse hover or keyboard focus over the trailing action button. Use tooltips sparingly and as
+        # a last resort. **Important:** This tooltip defaults to `type: :description`. In a few scenarios, `type: :label` may be
+        # more appropriate. Consult the <%= link_to_component(Primer::Alpha::Tooltip) %> documentation for more information.
+        #
+        # @param type [Symbol] (:description) <%= one_of(Primer::Alpha::Tooltip::TYPE_OPTIONS) %>
+        # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::Tooltip) %>.
+        renders_one :tooltip, lambda { |**system_arguments|
+          raise ArgumentError, "Buttons with a tooltip must have a unique `id` set on the `Button`." if @id.blank? && !Rails.env.production?
+
+          system_arguments[:for_id] = @id
+          system_arguments[:type] ||= :description
+
+          Primer::Alpha::Tooltip.new(**system_arguments)
+        }
+
+        # Used internally.
+        #
+        # @private
+        renders_one :private_content
+
+        attr_reader :list, :active, :disabled, :parent
+
+        # Whether or not this item is active.
+        #
+        # @return [Boolean]
+        alias active? active
+
+        # Whether or not this item is disabled.
+        #
+        # @return [Boolean]
+        alias disabled? disabled
+
+        # @param list [Primer::Alpha::ActionList] The list that contains this item. Used internally.
+        # @param parent [Primer::Alpha::ActionList::Item] This item's parent item. `nil` if this item is at the root. Used internally.
+        # @param label [String] Item label.
+        # @param label_classes [String] CSS classes that will be added to the label.
+        # @param truncate_label [Boolean] Truncate label with ellipsis.
+        # @param href [String] Link URL.
+        # @param role [String] ARIA role describing the function of the item.
+        # @param size [Symbol] Controls block sizing of the item.
+        # @param scheme [Symbol] Controls color/style based on behavior.
+        # @param disabled [Boolean] Disabled items are not clickable and visually dim.
+        # @param description_scheme [Symbol] Display description inline with label, or block on the next line.
+        # @param active [Boolean] Sets an active state on navigational items.
+        # @param on_click [String] JavaScript to execute when the item is clicked.
+        # @param id [String] Used internally.
+        # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+        def initialize(
+          list:,
+          label:,
+          label_classes: nil,
+          parent: nil,
+          truncate_label: false,
+          href: nil,
+          role: :listitem,
+          size: DEFAULT_SIZE,
+          scheme: DEFAULT_SCHEME,
+          disabled: false,
+          description_scheme: DEFAULT_DESCRIPTION_SCHEME,
+          active: false,
+          on_click: nil,
+          id: SecureRandom.hex,
+          **system_arguments
+        )
+          @list = list
+          @parent = parent
+          @label = label
+          @href = href
+          @truncate_label = truncate_label
+          @disabled = disabled
+          @active = active
+          @trailing_action_on_hover = false
+          @id = id
+          @system_arguments = system_arguments
+
+          @size = fetch_or_fallback(SIZE_OPTIONS, size, DEFAULT_SIZE)
+          @scheme = fetch_or_fallback(SCHEME_OPTIONS, scheme, DEFAULT_SCHEME)
+          @description_scheme = fetch_or_fallback(
+            DESCRIPTION_SCHEME_OPTIONS, description_scheme, DEFAULT_DESCRIPTION_SCHEME
+          )
+
+          @system_arguments[:classes] = class_names(
+            @system_arguments[:classes],
+            SCHEME_MAPPINGS[@scheme],
+            "ActionListItem",
+            "ActionListItem--navActive" => @active
+          )
+
+          @system_arguments[:role] = role
+
+          @system_arguments[:aria] ||= {}
+          @system_arguments[:aria][:disabled] = "true" if @disabled
+
+          @label_arguments = {
+            classes: class_names(
+              label_classes,
+              "ActionListItem-label",
+              "ActionListItem-label--truncate" => @truncate_label
+            )
+          }
+
+          @content_arguments = {
+            id: @id,
+            classes: class_names(
+              "ActionListContent",
+              SIZE_MAPPINGS[@size]
+            )
+          }
+
+          if @href && !@disabled
+            @content_arguments[:tag] = :a
+            @content_arguments[:href] = @href
+          else
+            @content_arguments[:tag] = :span
+            @content_arguments[:onclick] = on_click if on_click
+          end
+
+          @description_wrapper_arguments = {
+            classes: class_names(
+              "ActionListItem-descriptionWrap",
+              DESCRIPTION_SCHEME_MAPPINGS[@description_scheme]
+            )
+          }
+        end
+
+        private
+
+        def before_render
+          @system_arguments[:classes] = class_names(
+            @system_arguments[:classes],
+            "ActionListItem--withActions" => trailing_action.present?,
+            "ActionListItem--trailingActionHover" => @trailing_action_on_hover
+          )
+
+          return unless leading_visual
+
+          @content_arguments[:classes] = class_names(
+            @content_arguments[:classes],
+            "ActionListContent--visual16" => leading_visual,
+            "ActionListContent--blockDescription" => description && @description_scheme == :block
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+<%= render(Primer::BaseComponent.new(tag: :ul, role: @role, classes: "ActionListWrap")) 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 %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    # An ActionList is a styled list of links. It acts as the base component for many
+    # other menu-type components, including `ActionMenu` and `SelectPanel`, as well as
+    # the navigational component `NavList`.
+    #
+    # Each item in an action list can be augmented by specifying corresponding leading
+    # and/or trailing visuals.
+    class ActionList < Primer::Component
+      status :alpha
+
+      DEFAULT_ROLE = :list
+
+      DEFAULT_SCHEME = :full
+      SCHEME_MAPPINGS = {
+        DEFAULT_SCHEME => nil,
+        :inset => "ActionListWrap--inset"
+      }.freeze
+      SCHEME_OPTIONS = SCHEME_MAPPINGS.keys.freeze
+
+      # @private
+      def self.custom_element_name
+        @custom_element_name ||= name.split("::").last.underscore.dasherize
+      end
+
+      # @private
+      def custom_element_name
+        self.class.custom_element_name
+      end
+
+      # Heading text rendered above the list of items.
+      #
+      # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::ActionList::Heading) %>.
+      renders_one :heading, lambda { |**system_arguments|
+        Heading.new(list_id: @id, **system_arguments)
+      }
+
+      # Items.
+      #
+      # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::ActionList::Item) %>.
+      renders_many :items, lambda { |**system_arguments|
+        build_item(**system_arguments).tap do |item|
+          will_add_item(item)
+        end
+      }
+
+      # @param role [Boolean] ARIA role describing the function of the list. listbox and menu are a common values.
+      # @param item_classes [String] Additional CSS classes to attach to items.
+      # @param scheme [Symbol] <%= one_of(Primer::Alpha::ActionList::SCHEME_OPTIONS) %>. `inset` children are offset (vertically and horizontally) from list edges. `full` (default) children are flush (vertically and horizontally) with list edges.
+      # @param show_dividers [Boolean] Display a divider above each item in the list when it does not follow a header or divider.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(
+        role: DEFAULT_ROLE,
+        item_classes: nil,
+        scheme: DEFAULT_SCHEME,
+        show_dividers: false,
+        **system_arguments
+      )
+        @id = "action-list-#{SecureRandom.uuid}"
+        @role = role
+
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = :ul
+        @item_classes = item_classes
+        @scheme = fetch_or_fallback(SCHEME_OPTIONS, scheme, DEFAULT_SCHEME)
+        @show_dividers = show_dividers
+        @system_arguments[:classes] = class_names(
+          SCHEME_MAPPINGS[@scheme],
+          system_arguments[:classes],
+          "ActionListWrap",
+          "ActionListWrap--subGroup",
+          "ActionListWrap--divided" => @show_dividers
+        )
+
+        @list_wrapper_arguments = {}
+      end
+
+      # @private
+      def before_render
+        return if @sub_group
+
+        if heading.present?
+          @system_arguments[:"aria-labelledby"] = @id
+        elsif aria(:label, @system_arguments).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
+      def build_item(**system_arguments)
+        system_arguments[:classes] = class_names(
+          @item_classes,
+          system_arguments[:classes]
+        )
+
+        ActionList::Item.new(list: self, **system_arguments)
+      end
+
+      # @private
+      def will_add_item(_item); end
+    end
+  end
+end

data/app/components/primer/alpha/dialog/header.rb

@@ -24,7 +24,7 @@ module Primer
           @subtitle = subtitle
           @visually_hide_title = visually_hide_title
           @system_arguments = deny_tag_argument(**system_arguments)
-          @system_arguments[:tag] = :header
+          @system_arguments[:tag] = :div
           @system_arguments[:classes] = class_names(
             "Overlay-header",
             { "Overlay-header--divided": show_divider },

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

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

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    class NavList
+      # Items are rendered as styled links. They can optionally include leading and/or trailing visuals,
+      # such as icons, avatars, and counters. Items are selected by ID. IDs can be specified via the
+      # `selected_item_ids` argument, which accepts a list of valid IDs for the item. Items can also
+      # themselves contain sub items. Sub items are rendered collapsed by default.
+      class Item < Primer::Alpha::ActionList::Item
+        attr_reader :selected_by_ids, :sub_item
+
+        # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::ActionList::Item) %>.
+        renders_many :items, lambda { |**system_arguments|
+          raise "Items can only be nested 2 levels deep" if sub_item?
+
+          @list.build_item(parent: self, sub_item: true, **system_arguments).tap do |item|
+            @list.will_add_item(item)
+
+            if item.active?
+              @content_arguments[:classes] = class_names(
+                @content_arguments[:classes],
+                "ActionListContent--hasActiveSubItem"
+              )
+            end
+          end
+        }
+
+        # Whether or not this item is nested under a parent item.
+        #
+        # @return [Boolean]
+        alias sub_item? sub_item
+
+        # @param selected_item_id [Symbol] The ID of the currently selected list item. Used internally.
+        # @param selected_by_ids [Array<Symbol>] The list of IDs that select this item. In other words, if the `selected_item_id` attribute on the parent `NavList` is set to one of these IDs, the item will appear selected.
+        # @param expanded [Boolean] Whether this item shows (expands) or hides (collapses) its list of sub items.
+        # @param sub_item [Boolean] Whether or not this item is nested under a parent item. Used internally.
+        # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+        def initialize(selected_item_id: nil, selected_by_ids: [], sub_item: false, expanded: false, **system_arguments)
+          @selected_item_id = selected_item_id
+          @selected_by_ids = Array(selected_by_ids)
+          @expanded = expanded
+          @sub_item = sub_item
+
+          system_arguments[:classes] = class_names(
+            system_arguments[:classes],
+            "ActionListItem--subItem" => @sub_item
+          )
+
+          @sub_list_arguments = {
+            classes: class_names(
+              "ActionList",
+              "ActionList--subGroup"
+            )
+          }
+
+          overrides = { "data-item-id": @selected_by_ids.join(" ") }
+          overrides[:active] = @selected_by_ids.include?(@selected_item_id)
+
+          super(**system_arguments, **overrides)
+        end
+
+        # Cause this item to show its list of sub items when rendered.
+        def expand!
+          @expanded = true
+        end
+
+        def before_render
+          super
+
+          raise "Cannot render a trailing visual for an item with subitems" if items.present? && trailing_visual.present?
+
+          return if items.blank?
+
+          @content_arguments[:tag] = :button
+          @content_arguments[:"aria-expanded"] = @expanded.to_s
+          @content_arguments[:"data-action"] = "click:#{@list.custom_element_name}#handleItemWithSubItemClick"
+
+          with_private_trailing_action_icon(:"chevron-down", classes: "ActionListItem-collapseIcon")
+
+          @system_arguments[:classes] = class_names(
+            @system_arguments[:classes],
+            "ActionListItem--hasSubItem"
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+<nav-list>
+  <%= render_parent %>
+</nav-list>

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    class NavList
+      # 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
+        # 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.
+        #
+        # @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.
+        # @param component_klass [Class] A component class to use instead of the default `Primer::Alpha::NavList::Item` class.
+        # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::NavList::Item) %>.
+        renders_one :show_more_item, lambda { |src:, pages:, component_klass: NavList::Item, **system_arguments|
+          system_arguments[:classes] = class_names(
+            @item_classes,
+            system_arguments[:classes]
+          )
+          system_arguments[:id] = "ActionList--showMoreItem"
+          system_arguments[:hidden] = true
+          system_arguments[:href] = "#"
+          system_arguments[:data] ||= {}
+          system_arguments[:data][:target] = "nav-list.showMoreItem"
+          system_arguments[:data][:action] = "click:nav-list#showMore"
+          system_arguments[:data][:"current-page"] = "1"
+          system_arguments[:data][:"total-pages"] = pages.to_s
+          system_arguments[:label_classes] = class_names(
+            system_arguments[:label_classes],
+            "color-fg-accent"
+          )
+
+          component_klass.new(list: self, src: src, **system_arguments)
+        }
+
+        # @private
+        def self.custom_element_name
+          "nav-list"
+        end
+
+        # @param selected_item_id [Symbol] The ID of the currently selected item. Used internally.
+        # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+        def initialize(selected_item_id: nil, **system_arguments)
+          @system_arguments = system_arguments
+          @selected_item_id = selected_item_id
+          @system_arguments[:"data-target"] = "nav-list.list"
+
+          super(**@system_arguments)
+        end
+
+        # Cause this section to show its list of sub items when rendered.
+        def expand!
+          @expanded = true
+        end
+
+        # The items contained within this section.
+        #
+        # @return [Array<Primer::Alpha::ActionList::Item>]
+        def items
+          [*super, show_more_item].tap(&:compact!)
+        end
+
+        # @!parse
+        #   # Items.
+        #   #
+        #   # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::NavList::Item) %>.
+        #   renders_many :items
+
+        # @private
+        def build_item(component_klass: NavList::Item, **system_arguments)
+          component_klass.new(
+            **system_arguments,
+            selected_item_id: @selected_item_id,
+            list: self
+          )
+        end
+
+        # @private
+        def will_add_item(item)
+          item.parent.expand! if item.active? && item.parent
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+declare class NavListElement extends HTMLElement {
+    list: HTMLElement;
+    showMoreItem: HTMLElement;
+    focusMarkers: HTMLElement[];
+    connectedCallback(): void;
+    get showMoreDisabled(): boolean;
+    set showMoreDisabled(value: boolean);
+    set currentPage(value: number);
+    get currentPage(): number;
+    get totalPages(): number;
+    get paginationSrc(): string;
+    expandItem(item: HTMLElement): void;
+    collapseItem(item: HTMLElement): void;
+    itemIsExpanded(item: HTMLElement | null): boolean;
+    handleItemWithSubItemClick(e: Event): void;
+    private showMore;
+    private setShowMoreItemState;
+    private parseHTML;
+}
+declare global {
+    interface Window {
+        NavListElement: typeof NavListElement;
+    }
+}
+export {};

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

@@ -0,0 +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) %>
+    <% end %>
+    <li>
+      <%= section %>
+    </li>
+  <% end %>
+<% end %>