Class: Primer::Alpha::ActionList

Inherits:
Component
  • Object
show all
Defined in:
app/components/primer/alpha/action_list.rb,
app/components/primer/alpha/action_list/item.rb,
app/components/primer/alpha/action_list/divider.rb,
app/components/primer/alpha/action_list/heading.rb,
app/components/primer/alpha/action_list/form_wrapper.rb

Overview

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.

Defined Under Namespace

Classes: Divider, FormWrapper, Heading, Item

Constant Summary collapse

DEFAULT_ROLE = 
:list
:menu
DEFAULT_MENU_ITEM_ROLE = 
:menuitem
LIST_BOX_ITEM_ROLE = 
:option
DEFAULT_SCHEME = 
:full
SCHEME_MAPPINGS = 
{
  DEFAULT_SCHEME => nil,
  :inset => "ActionListWrap--inset"
}.freeze
SCHEME_OPTIONS = 
SCHEME_MAPPINGS.keys.freeze
DEFAULT_ARIA_SELECTION_VARIANT = 
:checked
ARIA_SELECTION_VARIANT_OPTIONS = 
[
  :selected,
  DEFAULT_ARIA_SELECTION_VARIANT,
].freeze
DEFAULT_SELECT_VARIANT = 
:none
SELECT_VARIANT_OPTIONS = 
[
  :single,
  :multiple,
  :multiple_checkbox,
  DEFAULT_SELECT_VARIANT
].freeze
SELECT_VARIANT_ROLE_MAP = 
{
  single: :menuitemradio,
  multiple: :menuitemcheckbox,
  multiple_checkbox: :menuitemcheckbox
}.freeze

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 Primer::AttributesHelper

Primer::AttributesHelper::PLURAL_ARIA_ATTRIBUTES, Primer::AttributesHelper::PLURAL_DATA_ATTRIBUTES

Instance Attribute Summary collapse

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 Primer::AttributesHelper

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

Methods included from ExperimentalSlotHelpers

included

Methods included from ExperimentalRenderHelpers

included

Constructor Details

#initialize(id: self.class.generate_id, role: nil, item_classes: nil, scheme: DEFAULT_SCHEME, show_dividers: false, aria_selection_variant: DEFAULT_ARIA_SELECTION_VARIANT, select_variant: DEFAULT_SELECT_VARIANT, form_arguments: {}, **system_arguments) ⇒ ActionList

Returns a new instance of ActionList.

Parameters:

  • id (String) (defaults to: self.class.generate_id) —

    HTML ID value.

  • role (Boolean) (defaults to: nil) —

    ARIA role describing the function of the list. listbox and menu are a common values.

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

    Additional CSS classes to attach to items.

  • scheme (Symbol) (defaults to: DEFAULT_SCHEME) —

    <%= 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.

  • show_dividers (Boolean) (defaults to: false) —

    Display a divider above each item in the list when it does not follow a header or divider.

  • select_variant (Symbol) (defaults to: DEFAULT_SELECT_VARIANT) —

    How items may be selected in the list. <%= one_of(Primer::Alpha::ActionList::SELECT_VARIANT_OPTIONS) %>

  • aria_selection_variant (Symbol) (defaults to: DEFAULT_ARIA_SELECTION_VARIANT) —

    Specifies which aria selection to use. <%= one_of(Primer::Alpha::ActionList::ARIA_SELECTION_VARIANT_OPTIONS) %>

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

    Allows an ‘ActionList` to act as a select list in multi- and single-select modes. Pass the `builder:` and `name:` options to this hash. `builder:` should be an instance of `ActionView::Helpers::FormBuilder`, which are created by the standard Rails `#form_with` and `#form_for` helpers. The `name:` option is the desired name of the field that will be included in the params sent to the server on form submission. NOTE: Consider using an <%= link_to_component(Primer::Alpha::ActionMenu) %> instead of using this feature directly.

  • system_arguments (Hash) —

    <%= link_to_system_arguments_docs %>

Raises:

  • (ArgumentError) 


134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'app/components/primer/alpha/action_list.rb', line 134

def initialize(
  id: self.class.generate_id,
  role: nil,
  item_classes: nil,
  scheme: DEFAULT_SCHEME,
  show_dividers: false,
  aria_selection_variant: DEFAULT_ARIA_SELECTION_VARIANT,
  select_variant: DEFAULT_SELECT_VARIANT,
  form_arguments: {},
  **system_arguments
)
  @system_arguments = system_arguments
  @id = id
  @system_arguments[:id] = @id
  @system_arguments[:tag] = :ul
  @item_classes = item_classes
  @scheme = fetch_or_fallback(SCHEME_OPTIONS, scheme, DEFAULT_SCHEME)
  @show_dividers = show_dividers
  @select_variant = select_variant
  @aria_selection_variant = aria_selection_variant
  @system_arguments[:classes] = class_names(
    SCHEME_MAPPINGS[@scheme],
    system_arguments[:classes],
    "ActionListWrap",
    "ActionListWrap--divided" => @show_dividers
  )

  @role = role || (allows_selection? ? MENU_ROLE : DEFAULT_ROLE)
  @system_arguments[:role] = @role

  @list_wrapper_arguments = {}

  @form_builder = form_arguments[:builder]
  @input_name = form_arguments[:name]

  return unless required_form_arguments_given? && !allows_selection?

  raise ArgumentError, "lists/menus that act as form inputs must also allow item selection (please pass the `select_variant:` option)"
end

Instance Attribute Details

#aria_selection_variant ⇒ Object (readonly)

Returns the value of attribute aria_selection_variant.



123
124
125
 
# File 'app/components/primer/alpha/action_list.rb', line 123

def aria_selection_variant
  @aria_selection_variant
end

#id ⇒ Object (readonly)

Returns the value of attribute id.



123
124
125
 
# File 'app/components/primer/alpha/action_list.rb', line 123

def id
  @id
end

#role ⇒ Object (readonly)

Returns the value of attribute role.



123
124
125
 
# File 'app/components/primer/alpha/action_list.rb', line 123

def role
  @role
end

#select_variant ⇒ Object (readonly)

Returns the value of attribute select_variant.



123
124
125
 
# File 'app/components/primer/alpha/action_list.rb', line 123

def select_variant
  @select_variant
end

Class Method Details

.custom_element_name ⇒ Object

:nocov:



48
49
50
 
# File 'app/components/primer/alpha/action_list.rb', line 48

def self.custom_element_name
  @custom_element_name ||= name.split("::").last.underscore.dasherize
end

Instance Method Details

#acts_as_form_input? ⇒ Boolean

Returns:

  • (Boolean) 


252
253
254
 
# File 'app/components/primer/alpha/action_list.rb', line 252

def acts_as_form_input?
  required_form_arguments_given? && allows_selection?
end

#acts_as_listbox? ⇒ Boolean

Returns:

  • (Boolean) 


240
241
242
 
# File 'app/components/primer/alpha/action_list.rb', line 240

def acts_as_listbox?
  @system_arguments[:role] == "listbox"
end

#acts_as_menu? ⇒ Boolean

Returns:

  • (Boolean) 


244
245
246
 
# File 'app/components/primer/alpha/action_list.rb', line 244

def acts_as_menu?
  @system_arguments[:role] == :menu || @system_arguments[:role] == :group
end

#allows_selection? ⇒ Boolean

Returns:

  • (Boolean) 


236
237
238
 
# File 'app/components/primer/alpha/action_list.rb', line 236

def allows_selection?
  single_select? || multi_select?
end

#before_render ⇒ Object 



175
176
177
178
179
180
 
# File 'app/components/primer/alpha/action_list.rb', line 175

def before_render
  return unless heading?

  @system_arguments[:"aria-labelledby"] = heading.title_id
  @system_arguments[:"aria-describedby"] = heading.subtitle_id if heading.subtitle?
end

#build_avatar_item(src:, username:, full_name: nil, full_name_scheme: Primer::Alpha::ActionList::Item::DEFAULT_DESCRIPTION_SCHEME, component_klass: ActionList::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: ActionList::Item) —

    The class to use instead of the default <%= link_to_component(Primer::Alpha::ActionList::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::Alpha::ActionList::Item) %>, or whatever class is passed as the ‘component_klass` argument.



217
218
219
220
221
222
223
224
225
226
 
# File 'app/components/primer/alpha/action_list.rb', line 217

def build_avatar_item(src:, username:, full_name: nil, full_name_scheme: Primer::Alpha::ActionList::Item::DEFAULT_DESCRIPTION_SCHEME, component_klass: ActionList::Item, avatar_arguments: {}, **system_arguments)
  build_item(label: username, description_scheme: full_name_scheme, component_klass: component_klass, **system_arguments).tap do |item|
    item.with_leading_visual_raw_content do
      # no alt text necessary for presentational item
      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: ActionList::Item, **system_arguments) ⇒ 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: ActionList::Item) —

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

  • system_arguments (Hash) —

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



189
190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'app/components/primer/alpha/action_list.rb', line 189

def build_item(component_klass: ActionList::Item, **system_arguments)
  if single_select? && system_arguments[:active] && items.count(&:active?).positive?
    raise ArgumentError, "only a single item may be active when select_variant is set to :single"
  end
  # rubocop:enable Style/IfUnlessModifier

  system_arguments[:classes] = class_names(
    @item_classes,
    system_arguments[:classes]
  )

  component_klass.new(list: self, **system_arguments)
end

#custom_element_name ⇒ Object 



53
54
55
 
# File 'app/components/primer/alpha/action_list.rb', line 53

def custom_element_name
  self.class.custom_element_name
end

#multi_select? ⇒ Boolean

Returns:

  • (Boolean) 


232
233
234
 
# File 'app/components/primer/alpha/action_list.rb', line 232

def multi_select?
  select_variant == :multiple || select_variant == :multiple_checkbox
end

#required_form_arguments_given? ⇒ Boolean

Returns:

  • (Boolean) 


248
249
250
 
# File 'app/components/primer/alpha/action_list.rb', line 248

def required_form_arguments_given?
  @form_builder && @input_name
end

#single_select? ⇒ Boolean

Returns:

  • (Boolean) 


228
229
230
 
# File 'app/components/primer/alpha/action_list.rb', line 228

def single_select?
  select_variant == :single
end

#will_add_item(_item) ⇒ Object 



257
 
# File 'app/components/primer/alpha/action_list.rb', line 257

def will_add_item(_item); end

#with_avatar_item(src:, username:, full_name: nil, full_name_scheme: Primer::Alpha::ActionList::Item::DEFAULT_DESCRIPTION_SCHEME, component_klass: ActionList::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: ActionList::Item) —

    The class to use instead of the default <%= link_to_component(Primer::Alpha::ActionList::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::Alpha::ActionList::Item) %>, or whatever class is passed as the ‘component_klass` argument.



10
11
 
# File 'app/components/primer/alpha/action_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: ActionList::Item, avatar_arguments: {}, **system_arguments, &block)
end

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

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

Parameters:

  • system_arguments (Hash) —

    The arguments accepted by <%= link_to_component(Primer::Alpha::ActionList::Divider) %>.



4
5
 
# File 'app/components/primer/alpha/action_list.rb', line 4

def with_divider(**system_arguments, &block)
end

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

Adds an item to the list.

Parameters:

  • component_klass (Class) —

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

  • system_arguments (Hash) —

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



5
6
 
# File 'app/components/primer/alpha/action_list.rb', line 5

def with_item(**system_arguments, &block)
end