Class: Primer::Alpha::ActionList::Item

Inherits:

Component

• Object
• ViewComponent::Base
• Component
• Primer::Alpha::ActionList::Item

Defined in:

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

Overview

An individual ‘ActionList` item. Items can optionally include leading and/or trailing visuals, such as icons, avatars, and counters.

Direct Known Subclasses

Beta::NavList::Item

Constant Summary

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

DEFAULT_TRUNCATION_BEHAVIOR =

:none

TRUNCATION_BEHAVIOR_MAPPINGS =

{
  DEFAULT_TRUNCATION_BEHAVIOR => nil,
  false => nil,
  :show_tooltip => "ActionListItem-label--truncate",
  :truncate => "ActionListItem-label--truncate",
  true => "ActionListItem-label--truncate"
}

TRUNCATION_BEHAVIOR_OPTIONS =

TRUNCATION_BEHAVIOR_MAPPINGS.keys.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

• #active ⇒ Object (also: #active?) readonly

  Returns the value of attribute active.

• #disabled ⇒ Object (also: #disabled?) readonly

  Returns the value of attribute disabled.

• #href ⇒ Object readonly

  Returns the value of attribute href.

• #id ⇒ Object readonly

  Returns the value of attribute id.

• #item_id ⇒ Object readonly

  Returns the value of attribute item_id.

• #list ⇒ Object readonly

  Returns the value of attribute list.

• #parent ⇒ Object readonly

  Returns the value of attribute parent.

Instance Method Summary

• #initialize(list:, label: nil, item_id: nil, label_classes: nil, label_arguments: {}, content_arguments: {}, form_arguments: {}, parent: nil, truncate_label: :none, href: nil, role: nil, size: DEFAULT_SIZE, scheme: DEFAULT_SCHEME, disabled: false, description_scheme: DEFAULT_DESCRIPTION_SCHEME, active: false, on_click: nil, id: self.class.generate_id, **system_arguments) ⇒ Item constructor

  A new instance of Item.

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(list:, label: nil, item_id: nil, label_classes: nil, label_arguments: {}, content_arguments: {}, form_arguments: {}, parent: nil, truncate_label: :none, href: nil, role: nil, size: DEFAULT_SIZE, scheme: DEFAULT_SCHEME, disabled: false, description_scheme: DEFAULT_DESCRIPTION_SCHEME, active: false, on_click: nil, id: self.class.generate_id, **system_arguments) ⇒ Item

Returns a new instance of Item.

Parameters:

• list (Primer::Alpha::ActionList) —

  The list that contains this item. Used internally.

• parent (Primer::Alpha::ActionList::Item) (defaults to: nil) —

  This item’s parent item. ‘nil` if this item is at the root. Used internally.

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

  Item label. If no label is provided, content is used.

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

  An ID that will be attached to the item’s ‘<li>` element as `data-item-id` for distinguishing between items, perhaps in JavaScript.

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

  CSS classes that will be added to the label.

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

  <%= link_to_system_arguments_docs %> used to construct the label.

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

  <%= link_to_system_arguments_docs %> used to construct the item’s anchor or button tag.

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

  Allows the item to submit a form on click. The URL passed in the ‘href:` option will be used as the form action. Pass the `method:` option to this hash to control what kind of request is made, <%= one_of(Primer::Alpha::ActionList::FormWrapper::HTTP_METHOD_OPTIONS) %> The `name:` option is required and specifies the desired name of the field that will be included in the params sent to the server on form submission. Specify the `value:` option to send a custom value to the server; otherwise the value of `name:` is sent.

• truncate_label (Boolean | Symbol) (defaults to: :none) —

  How the label should be truncated when the text does not fit inside the bounds of the list item. <%= one_of(Primer::Alpha::ActionList::Item::TRUNCATION_BEHAVIOR_OPTIONS) %> Pass ‘false` or `:none` to wrap label text. Pass `true` or `:truncate` to truncate labels with ellipses. Pass `:show_tooltip` to show the entire label contents in a tooltip when the item is hovered.

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

  Link URL.

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

  ARIA role describing the function of the item.

• size (Symbol) (defaults to: DEFAULT_SIZE) —

  Controls block sizing of the item.

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

  Controls color/style based on behavior.

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

  Disabled items are not clickable and visually dim.

• description_scheme (Symbol) (defaults to: DEFAULT_DESCRIPTION_SCHEME) —

  Display description inline with label, or block on the next line. <%= one_of(Primer::Alpha::ActionList::Item::DESCRIPTION_SCHEME_OPTIONS) %>

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

  If the parent list’s ‘select_variant` is set to `:single` or `:multiple`, causes this item to render checked.

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

  JavaScript to execute when the item is clicked.

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

  Used internally.

• system_arguments (Hash) —

  <%= link_to_system_arguments_docs %>

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

def initialize(
  list:,
  label: nil,
  item_id: nil,
  label_classes: nil,
  label_arguments: {},
  content_arguments: {},
  form_arguments: {},
  parent: nil,
  truncate_label: :none,
  href: nil,
  role: nil,
  size: DEFAULT_SIZE,
  scheme: DEFAULT_SCHEME,
  disabled: false,
  description_scheme: DEFAULT_DESCRIPTION_SCHEME,
  active: false,
  on_click: nil,
  id: self.class.generate_id,
  **system_arguments
)
  @list = list
  @parent = parent
  @label = label
  @item_id = item_id
  @href = href || content_arguments[:href]
  @truncate_label = truncate_label
  @disabled = disabled
  @active = active
  @id = id
  @system_arguments = system_arguments
  @content_arguments = content_arguments
  @form_wrapper = FormWrapper.new(list: @list, action: @href, **form_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--disabled" => @disabled
  )

  @system_arguments[:data] = merge_data(
    @system_arguments, {
      data: {
        targets: "#{list_class.custom_element_name}.items",
        **(@item_id ? { item_id: @item_id } : {})
      }
    }
  )

  @label_arguments = {
    **label_arguments,
    classes: class_names(
      label_classes,
      label_arguments[:classes],
      "ActionListItem-label",
      TRUNCATION_BEHAVIOR_MAPPINGS[@truncate_label],
    )
  }

  @content_arguments[:id] = @id
  @content_arguments[:classes] = class_names(
    @content_arguments[:classes],
    "ActionListContent",
    SIZE_MAPPINGS[@size]
  )

  unless @content_arguments[:tag]
    if @href && @form_wrapper.get? && !@disabled
      @content_arguments[:tag] = :a
      @content_arguments[:href] = @href
    else
      @content_arguments[:tag] = :button
      @content_arguments[:type] = @form_wrapper.form_required? ? :submit : :button
      @content_arguments[:onclick] = on_click if on_click
    end
  end

  if @content_arguments[:tag] != :button && @form_wrapper.form_required?
    raise ArgumentError, "items that submit forms must use a \"button\" tag instead of \"#{@content_arguments[:tag]}\""
  end

  if @content_arguments[:tag] != :button && @list.acts_as_form_input?
    raise ArgumentError, "items within lists/menus that act as form inputs must use \"button\" tags instead of \"#{@content_arguments[:tag]}\""
  end

  if @disabled
    @content_arguments[:aria] ||= merge_aria(
      @content_arguments,
      { aria: { disabled: "true" } }
    )
  end

  @content_arguments[:role] = role ||
                              if @list.acts_as_listbox?
                                ActionList::LIST_BOX_ITEM_ROLE
                              elsif @list.allows_selection?
                                ActionList::SELECT_VARIANT_ROLE_MAP[@list.select_variant]
                              elsif @list.acts_as_menu?
                                ActionList::DEFAULT_MENU_ITEM_ROLE
                              end

  @system_arguments[:role] = @list.acts_as_menu? || @list.acts_as_listbox? ? :none : nil

  @description_wrapper_arguments = {
    classes: class_names(
      "ActionListItem-descriptionWrap",
      DESCRIPTION_SCHEME_MAPPINGS[@description_scheme]
    )
  }
end

Instance Attribute Details

#active ⇒ Object (readonly) Also known as: active?

Returns the value of attribute active.

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

def active
  @active
end

#disabled ⇒ Object (readonly) Also known as: disabled?

Returns the value of attribute disabled.

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

def disabled
  @disabled
end

#href ⇒ Object (readonly)

Returns the value of attribute href.

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

def href
  @href
end

#id ⇒ Object (readonly)

Returns the value of attribute id.

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

def id
  @id
end

#item_id ⇒ Object (readonly)

Returns the value of attribute item_id.

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

def item_id
  @item_id
end

#list ⇒ Object (readonly)

Returns the value of attribute list.

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

def list
  @list
end

#parent ⇒ Object (readonly)

Returns the value of attribute parent.

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

def parent
  @parent
end