Class: Primer::Beta::AutoComplete

Inherits:

Component

• Object
• ViewComponent::Base
• Component
• Primer::Beta::AutoComplete

Defined in:

app/components/primer/beta/auto_complete.rb,
app/components/primer/beta/auto_complete/item.rb

Overview

Use AutoComplete to provide a user with a list of selectable suggestions that appear when they type into the input field. This list is populated by server search results.

Defined Under Namespace

Classes: Item

Constant Summary

DEFAULT_SIZE =

:medium

SIZE_MAPPINGS =

{
  :small => "FormControl-small",
  DEFAULT_SIZE => "FormControl-medium",
  :large => "FormControl-large"
}.freeze

SIZE_OPTIONS =

SIZE_MAPPINGS.keys

DEFAULT_WIDTH =

:auto

WIDTH_MAPPINGS =

{
  DEFAULT_WIDTH => "Overlay--width-auto",
  :small => "Overlay--width-small",
  :medium => "Overlay--width-medium",
  :large => "Overlay--width-large",
  :xlarge => "Overlay--width-xlarge",
  :xxlarge => "Overlay--width-xxlarge"
}.freeze

WIDTH_OPTIONS =

WIDTH_MAPPINGS.keys

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

Instance Method Summary

• #before_render ⇒ Object

  add input and results without needing to explicitly call them in the view.

• #initialize(label_text:, src:, list_id:, input_id:, input_name: nil, placeholder: nil, show_clear_button: false, visually_hide_label: false, size: DEFAULT_SIZE, full_width: false, width: DEFAULT_WIDTH, disabled: false, invalid: false, inset: false, monospace: false, **system_arguments) ⇒ AutoComplete constructor

  A new instance of AutoComplete.

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(label_text:, src:, list_id:, input_id:, input_name: nil, placeholder: nil, show_clear_button: false, visually_hide_label: false, size: DEFAULT_SIZE, full_width: false, width: DEFAULT_WIDTH, disabled: false, invalid: false, inset: false, monospace: false, **system_arguments) ⇒ AutoComplete

Returns a new instance of AutoComplete.

Examples:

Leading visual

@description
  Display any Octicon as a leading visual within the field
@code
  <%= render(Primer::Beta::AutoComplete.new(label_text: "Select a fruit", src: "/view-components/rails-app/auto_complete", input_id:"input-id-1", list_id: "list-id-1")) do |component| %>
    <% component.with_leading_visual_icon(icon: :search) %>
  <% end %>

Trailing action

@description
  Show a clear button
@code
  <%= render(Primer::Beta::AutoComplete.new(label_text: "Select a fruit", input_id: "input-id-2", list_id: "list-id-2", src: "/view-components/rails-app/auto_complete", show_clear_button: true )) %>

Visually hidden label

@description
  A non-visible label may be rendered with `visually_hide_label: true`, but it is highly discouraged. See <%= link_to_accessibility %>.
@code
  <%= render(Primer::Beta::AutoComplete.new(label_text: "Select a fruit", input_id: "fruits-input--custom-results-1", list_id: "fruits-popup--custom-result-1", src: "/view-components/rails-app/auto_complete", visually_hide_label: true)) do |component| %>
    <% component.with_leading_visual_icon(icon: :search) %>
  <% end %>

Full width field

@description
  To allow field to span width of its container, set `full_width` to `true`.
@code
  <%= render(Primer::Beta::AutoComplete.new(label_text: "Select a fruit", input_id: "fruits-input--custom-results-2", list_id: "fruits-popup--custom-results-2", src: "/view-components/rails-app/auto_complete", full_width: true)) do |component| %>
    <% component.with_leading_visual_icon(icon: :search) %>
  <% end %>

Inset variant

@description
  Use the `inset` variant to change the input background color to be subtle.
@code
  <%= render(Primer::Beta::AutoComplete.new(label_text: "Select a fruit", input_id: "fruits-input--custom-results-2", list_id: "fruits-popup--custom-results-2", src: "/view-components/rails-app/auto_complete", inset: true)) do |component| %>
    <% component.with_leading_visual_icon(icon: :search) %>
  <% end %>

Monospace variant

@description
  Use the `monospace` variant to change the input font family.
@code
  <%= render(Primer::Beta::AutoComplete.new(label_text: "Select a fruit", input_id: "fruits-input--custom-results-2", list_id: "fruits-popup--custom-results-2", src: "/view-components/rails-app/auto_complete", monospace: true)) do |component| %>
    <% component.with_leading_visual_icon(icon: :search) %>
  <% end %>

With custom classes for the input

<%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/view-components/rails-app/auto_complete", input_id: "fruits-input--custom-input", list_id: "fruits-popup--custom-input")) do |component| %>
  <% component.with_input(classes: "custom-class") %>
<% end %>

With custom classes for the results

<%= render(Primer::Beta::AutoComplete.new(label_text: "Fruits", src: "/view-components/rails-app/auto_complete", input_id: "fruits-input--custom-results", list_id: "fruits-popup--custom-results")) do |component| %>
  <% component.with_results(classes: "custom-class") %>
<% end %>

Parameters:

• label_text (String) —

  The label of the input.

• src (String) —

  The route to query.

• input_id (String) —

  Id of the input element.

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

  Optional name of the input element, defaults to input_id when not set.

• list_id (String) —

  Id of the list element.

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

  Controls if the label is visible. If true, screen reader only text will be added.

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

  Adds optional clear button.

• system_arguments (Hash) —

  <%= link_to_system_arguments_docs %>

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

  Input size can be small, medium (default), or large

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

  Input can be full-width or fit to content

• width (String) (defaults to: DEFAULT_WIDTH) —

  Optional parameter to set max width of results list. <%= one_of(Primer::Beta::AutoComplete::WIDTH_OPTIONS) %>

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

  Disabled input

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

  Invalid input

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

  The placeholder text displayed within the input

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

  subtle input background color

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

  monospace input font family

# File 'app/components/primer/beta/auto_complete.rb', line 176

def initialize(label_text:, src:, list_id:, input_id:, input_name: nil, placeholder: nil, show_clear_button: false, visually_hide_label: false, size: DEFAULT_SIZE, full_width: false, width: DEFAULT_WIDTH, disabled: false, invalid: false, inset: false, monospace: false, **system_arguments)
  @label_text = label_text
  @list_id = list_id
  @input_id = input_id
  @input_name = input_name || input_id
  @placeholder = placeholder
  @visually_hide_label = visually_hide_label
  @show_clear_button = show_clear_button
  @system_arguments = deny_tag_argument(**system_arguments)
  @system_arguments[:tag] = "auto-complete"
  @system_arguments[:src] = src
  @system_arguments[:for] = list_id
  @disabled = disabled
  @invalid = invalid
  @size = size
  @inset = inset
  @monospace = monospace
  @full_width = full_width
  @width = width
  @field_wrap_classes = class_names(
    "FormControl-input-wrap",
    SIZE_MAPPINGS[fetch_or_fallback(SIZE_OPTIONS, @size, DEFAULT_SIZE)],
    "FormControl-input-wrap--trailingAction": show_clear_button
  )
  @form_group_classes = class_names(
    "FormControl",
    "FormControl--fullWidth": full_width
  )
  @overlay_classes = class_names(
    "Overlay",
    "Overlay--height-auto",
    WIDTH_MAPPINGS[fetch_or_fallback(WIDTH_OPTIONS, @width, DEFAULT_WIDTH)]
  )
end

Instance Method Details

#before_render ⇒ Object

add input and results without needing to explicitly call them in the view

# File 'app/components/primer/beta/auto_complete.rb', line 212

def before_render
  with_results(classes: "") unless results?
  with_input(classes: "") unless input?
end