Class: Primer::Beta::NavList

Inherits:
Component
  • Object
show all
Defined in:
app/components/primer/beta/nav_list.rb,
app/components/primer/beta/nav_list/item.rb,
app/components/primer/beta/nav_list/group.rb,
app/components/primer/beta/nav_list/divider.rb,
app/components/primer/beta/nav_list/heading.rb

Overview

‘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 group in a nav list is a list of links.

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 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 ‘selected_item_id` argument to select the appropriate item.

Direct Known Subclasses

Alpha::NavList

Defined Under Namespace

Classes: Divider, Group, Heading, Item

Constant Summary

Constants inherited from Component

Component::INVALID_ARIA_LABEL_TAGS

Constants included from Status::Dsl

Status::Dsl::STATUSES

Constants included from ViewHelper

ViewHelper::HELPERS

Constants included from TestSelectorHelper

TestSelectorHelper::TEST_SELECTOR_TAG

Constants included from FetchOrFallbackHelper

FetchOrFallbackHelper::InvalidValueError

Constants included from AttributesHelper

AttributesHelper::PLURAL_ARIA_ATTRIBUTES, AttributesHelper::PLURAL_DATA_ATTRIBUTES

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Component

deprecated?, generate_id

Methods included from JoinStyleArgumentsHelper

#join_style_arguments

Methods included from TestSelectorHelper

#add_test_selector

Methods included from FetchOrFallbackHelper

#fetch_or_fallback, #fetch_or_fallback_boolean, #silence_deprecations?

Methods included from ClassNameHelper

#class_names

Methods included from AttributesHelper

#aria, #data, #merge_aria, #merge_data, #merge_prefixed_attribute_hashes

Constructor Details

#initialize(selected_item_id: nil, **system_arguments) ⇒ NavList

Returns a new instance of NavList.

Parameters:

  • selected_item_id (Symbol) (defaults to: nil) —

    The ID of the currently selected item. The default is ‘nil`, meaning no item is selected.

  • system_arguments (Hash) —

    <%= link_to_system_arguments_docs %>



104
105
106
107
 
# File 'app/components/primer/beta/nav_list.rb', line 104

def initialize(selected_item_id: nil, **system_arguments)
  @system_arguments = system_arguments
  @selected_item_id = selected_item_id
end

Class Method Details

.custom_element_name ⇒ Object 



22
23
24
 
# File 'app/components/primer/beta/nav_list.rb', line 22

def self.custom_element_name
  "nav-list"
end

Instance Method Details

#build_avatar_item(src:, username:, full_name: nil, full_name_scheme: Primer::Alpha::ActionList::Item::DEFAULT_DESCRIPTION_SCHEME, component_klass: Primer::Beta::NavList::Item, avatar_arguments: {}, **system_arguments) ⇒ Object

Builds a new avatar item but does not add it to the list. Avatar items are a convenient way to accessibly add an item with a leading avatar image. Use this method instead of the ‘#with_avatar_item` slot if you need to render an avatar item outside the context of a list, eg. if rendering additional items to append to an existing list, perhaps via a separate HTTP request.

Parameters:

  • src (String) —

    The source url of the avatar image.

  • username (String) —

    The username associated with the avatar.

  • full_name (String) (defaults to: nil) —

    Optional. The user’s full name.

  • full_name_scheme (Symbol) (defaults to: Primer::Alpha::ActionList::Item::DEFAULT_DESCRIPTION_SCHEME) —

    Optional. How to display the user’s full name. <%= one_of(Primer::Alpha::ActionList::Item::DESCRIPTION_SCHEME_OPTIONS) %>

  • component_klass (Class) (defaults to: Primer::Beta::NavList::Item) —

    The class to use instead of the default <%= link_to_component(Primer::Beta::NavList::Item) %>

  • avatar_arguments (Hash) (defaults to: {}) —

    Optional. The arguments accepted by <%= link_to_component(Primer::Beta::Avatar) %>

  • system_arguments (Hash) —

    These arguments are forwarded to <%= link_to_component(Primer::Beta::NavList::Item) %>, or whatever class is passed as the ‘component_klass` argument.



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'app/components/primer/beta/nav_list.rb', line 139

def build_avatar_item(src:, username:, full_name: nil, full_name_scheme: Primer::Alpha::ActionList::Item::DEFAULT_DESCRIPTION_SCHEME, component_klass: Primer::Beta::NavList::Item, avatar_arguments: {}, **system_arguments)
  component_klass.new(
    list: top_level_group,
    selected_item_id: @selected_item_id,
    label: username,
    description_scheme: full_name_scheme,
    **system_arguments
  ).tap do |item|
    item.with_leading_visual_raw_content do
      # no alt text necessary
      item.render(Primer::Beta::Avatar.new(src: src, **avatar_arguments, role: :presentation, size: 16))
    end

    item.with_description_content(full_name) if full_name
  end
end

#build_item(component_klass: Primer::Beta::NavList::Item, **system_arguments, &block) ⇒ Object

Builds a new item but does not add it to the list. Use this method instead of the ‘#with_item` slot if you need to render an item outside the context of a list, eg. if rendering additional items to append to an existing list, perhaps via a separate HTTP request.

Parameters:

  • component_klass (Class) (defaults to: Primer::Beta::NavList::Item) —

    The class to use instead of the default <%= link_to_component(Primer::Beta::NavList::Item) %>

  • system_arguments (Hash) —

    These arguments are forwarded to <%= link_to_component(Primer::Beta::NavList::Item) %>, or whatever class is passed as the ‘component_klass` argument.



116
117
118
119
120
121
122
123
 
# File 'app/components/primer/beta/nav_list.rb', line 116

def build_item(component_klass: Primer::Beta::NavList::Item, **system_arguments, &block)
  component_klass.new(
    list: top_level_group,
    selected_item_id: @selected_item_id,
    **system_arguments,
    &block
  )
end

#with_avatar_item(src:, username:, full_name: nil, full_name_scheme: Primer::Alpha::ActionList::Item::DEFAULT_DESCRIPTION_SCHEME, component_klass: Primer::Beta::NavList::Item, avatar_arguments: {}, **system_arguments, &block) ⇒ Object

Adds an avatar item to the list. Avatar items are a convenient way to accessibly add an item with a leading avatar image.

Parameters:

  • src (String) —

    The source url of the avatar image.

  • username (String) —

    The username associated with the avatar.

  • full_name (String) (defaults to: nil) —

    Optional. The user’s full name.

  • full_name_scheme (Symbol) (defaults to: Primer::Alpha::ActionList::Item::DEFAULT_DESCRIPTION_SCHEME) —

    Optional. How to display the user’s full name. <%= one_of(Primer::Alpha::ActionList::Item::DESCRIPTION_SCHEME_OPTIONS) %>

  • component_klass (Class) (defaults to: Primer::Beta::NavList::Item) —

    The class to use instead of the default <%= link_to_component(Primer::Beta::NavList::Item) %>

  • avatar_arguments (Hash) (defaults to: {}) —

    Optional. The arguments accepted by <%= link_to_component(Primer::Beta::Avatar) %>

  • system_arguments (Hash) —

    These arguments are forwarded to <%= link_to_component(Primer::Beta::NavList::Item) %>, or whatever class is passed as the ‘component_klass` argument.



10
11
 
# File 'app/components/primer/beta/nav_list.rb', line 10

def with_avatar_item(src:, username:, full_name: nil, full_name_scheme: Primer::Alpha::ActionList::Item::DEFAULT_DESCRIPTION_SCHEME, component_klass: Primer::Beta::NavList::Item, avatar_arguments: {}, **system_arguments, &block)
end

#with_divider(**system_arguments, &block) ⇒ Object

Adds a divider to the list. Dividers visually separate items and groups.

Parameters:

  • system_arguments (Hash) —

    The arguments accepted by <%= link_to_component(Primer::Beta::NavList::Divider) %>.



4
5
 
# File 'app/components/primer/beta/nav_list.rb', line 4

def with_divider(**system_arguments, &block)
end

#with_group(**system_arguments, &block) ⇒ Object

Adds a group to the list. A group is a list of links and a (required) heading.

Parameters:

  • system_arguments (Hash) —

    The arguments accepted by <%= link_to_component(Primer::Beta::NavList::Group) %>.



4
5
 
# File 'app/components/primer/beta/nav_list.rb', line 4

def with_group(**system_arguments, &block)
end

#with_item(component_klass: Primer::Beta::NavList::Item, **system_arguments, &block) ⇒ Object

Adds an item to the list.

Parameters:

  • component_klass (Class) (defaults to: Primer::Beta::NavList::Item) —

    The class to use instead of the default <%= link_to_component(Primer::Beta::NavList::Item) %>

  • system_arguments (Hash) —

    These arguments are forwarded to <%= link_to_component(Primer::Beta::NavList::Item) %>, or whatever class is passed as the ‘component_klass` argument.



5
6
 
# File 'app/components/primer/beta/nav_list.rb', line 5

def with_item(component_klass: Primer::Beta::NavList::Item, **system_arguments, &block)
end