Method: Primer::Alpha::ActionList::Item#initialize

Defined in:

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

#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