yattho_view_components 0.0.1

data/app/components/yattho/alpha/action_list.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Yattho
+  module Alpha
+    # 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.
+    class ActionList < Yattho::Component
+      status :alpha
+
+      DEFAULT_ROLE = :list
+
+      DEFAULT_SCHEME = :full
+      SCHEME_MAPPINGS = {
+        DEFAULT_SCHEME => nil,
+        :inset => "ActionListWrap--inset"
+      }.freeze
+      SCHEME_OPTIONS = SCHEME_MAPPINGS.keys.freeze
+
+      # :nocov:
+      # @private
+      def self.custom_element_name
+        @custom_element_name ||= name.split("::").last.underscore.dasherize
+      end
+
+      # @private
+      def custom_element_name
+        self.class.custom_element_name
+      end
+      # :nocov:
+
+      # Heading text rendered above the list of items.
+      #
+      # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Yattho::Alpha::ActionList::Heading) %>.
+      renders_one :heading, lambda { |**system_arguments|
+        Heading.new(list_id: @id, **system_arguments)
+      }
+
+      # Items.
+      #
+      # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Yattho::Alpha::ActionList::Item) %>.
+      renders_many :items, lambda { |**system_arguments|
+        build_item(**system_arguments).tap do |item|
+          will_add_item(item)
+        end
+      }
+
+      # @param role [Boolean] ARIA role describing the function of the list. listbox and menu are a common values.
+      # @param item_classes [String] Additional CSS classes to attach to items.
+      # @param scheme [Symbol] <%= one_of(Yattho::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.
+      # @param show_dividers [Boolean] Display a divider above each item in the list when it does not follow a header or divider.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(
+        role: DEFAULT_ROLE,
+        item_classes: nil,
+        scheme: DEFAULT_SCHEME,
+        show_dividers: false,
+        **system_arguments
+      )
+        @id = self.class.generate_id
+        @role = role
+
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = :ul
+        @item_classes = item_classes
+        @scheme = fetch_or_fallback(SCHEME_OPTIONS, scheme, DEFAULT_SCHEME)
+        @show_dividers = show_dividers
+        @system_arguments[:classes] = class_names(
+          SCHEME_MAPPINGS[@scheme],
+          system_arguments[:classes],
+          "ActionListWrap",
+          "ActionListWrap--subGroup",
+          "ActionListWrap--divided" => @show_dividers
+        )
+
+        @list_wrapper_arguments = {}
+      end
+
+      # @private
+      def before_render
+        if heading.present?
+          @system_arguments[:'aria-labelledby'] = @id
+        elsif aria(:label, @system_arguments).blank?
+          raise ArgumentError, "An aria-label or heading must be provided"
+        end
+
+        return if items.blank?
+
+        @list_wrapper_arguments[:classes] = class_names(
+          @list_wrapper_arguments[:classes],
+          "ActionListItem--hasSubItem"
+        )
+      end
+
+      # @private
+      def build_item(**system_arguments)
+        system_arguments[:classes] = class_names(
+          @item_classes,
+          system_arguments[:classes]
+        )
+
+        ActionList::Item.new(list: self, **system_arguments)
+      end
+
+      # @private
+      def will_add_item(_item); end
+    end
+  end
+end

data/app/components/yattho/alpha/auto_complete/auto_complete.html.erb

@@ -0,0 +1,24 @@
+<%= render Yattho::BaseComponent.new(**@system_arguments) do %>
+  <label for="<%= @input_id %>" class="<%= @label_classes %>">
+    <% if @is_label_visible %>
+      <%= @label_text %>
+    <% else %>
+      <span class="sr-only"><%= @label_text %></span>
+    <% end %>
+  </label>
+  <span class="autocomplete-body">
+    <% if @with_icon %>
+      <div class="form-control autocomplete-embedded-icon-wrap">
+        <%= render Yattho::Beta::Octicon.new(:search) %>
+    <% end %>
+    <%= input %>
+    <% if @is_clearable %>
+      <button id="<%= @input_id %>-clear" class="btn-octicon" aria-label="Clear"><%= yattho_octicon "x" %></button>
+    <% end %>
+    <% if @with_icon %>
+      </div>
+    <% end %>
+    <%= results %>
+  </span>
+  <div id="<%= @list_id %>-feedback" class="sr-only"></div>
+<% end %>

data/app/components/yattho/alpha/auto_complete/item.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Yattho
+  module Alpha
+    class AutoComplete
+      # Use `AutoCompleteItem` to list results of an auto-completed search.
+      class Item < Yattho::Component
+        status :deprecated
+
+        # @example Default
+        #   <%= render(Yattho::Alpha::AutoComplete.new(label_text: "Fruits", src: "/auto_complete", input_id: "fruits-input--custom-results", list_id: "fruits-popup--custom-results")) do |component| %>
+        #     <% component.results(classes: "custom-class") do %>
+        #       <%= render(Yattho::Alpha::AutoComplete::Item.new(selected: true, value: "apple")) do %>
+        #         Apple
+        #       <% end %>
+        #       <%= render(Yattho::Alpha::AutoComplete::Item.new(value: "orange")) do %>
+        #         Orange
+        #       <% end %>
+        #     <% end %>
+        #   <% end %>
+        #
+        # @param value [String] Value of the item.
+        # @param selected [Boolean] Whether the item is selected.
+        # @param disabled [Boolean] Whether the item is disabled.
+        # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+        def initialize(value:, selected: false, disabled: false, **system_arguments)
+          @system_arguments = deny_tag_argument(**system_arguments)
+          @system_arguments[:tag] = :li
+          @system_arguments[:role] = :option
+          @system_arguments[:'data-autocomplete-value'] = value
+          @system_arguments[:'aria-selected'] = true if selected
+          @system_arguments[:'aria-disabled'] = true if disabled
+          @system_arguments[:classes] = class_names(
+            "autocomplete-item",
+            system_arguments[:classes],
+            "disabled" => disabled
+          )
+        end
+
+        def call
+          render(Yattho::BaseComponent.new(**@system_arguments)) { content }
+        end
+      end
+    end
+  end
+end

data/app/components/yattho/alpha/auto_complete.css

@@ -0,0 +1,130 @@
+/* autocomplete */
+
+/* This file can be deprecated when AutoComplete is upstreamed to YVC + rolled out to dotcom https://github.com/github/yattho/issues/796
+** AutoComplete relies on FormControl, Overlay and ActionList CSS */
+
+/* Stacked label (default) */
+
+.autocomplete-label-stacked {
+  display: block;
+  margin-bottom: 6px;
+}
+
+/* Inline label (non-default) */
+
+.autocomplete-label-inline {
+  display: inline;
+  margin-right: 6px;
+}
+
+/* Switch to stacked at smaller viewport */
+
+@media (max-width: 543.98px) {
+  .autocomplete-label-inline {
+    display: block;
+    margin-bottom: 6px;
+  }
+}
+
+/* Wrapper for the input and result elements to ensure alignment */
+
+.autocomplete-body {
+  position: relative;
+  display: inline;
+}
+
+/* Wrapper and conditional styles for when an icon is added */
+
+.autocomplete-embedded-icon-wrap {
+  display: inline-flex;
+  padding: 4px 8px;
+  align-items: center;
+}
+
+.autocomplete-embedded-icon-wrap:focus-within {
+    border-color: var(--color-accent-fg);
+
+    border-color: var(--color-accent-fg);
+
+    outline: none;
+
+    box-shadow: inset 0 0 0 1px var(--color-accent-fg);
+  }
+
+.autocomplete-embedded-icon-wrap .form-control {
+    padding: 0;
+    margin-left: 8px;
+    border: none;
+    box-shadow: none;
+  }
+
+.autocomplete-embedded-icon-wrap .form-control:focus {
+      box-shadow: none;
+    }
+
+.autocomplete-embedded-icon-wrap .form-control:focus-visible {
+      box-shadow: none;
+    }
+
+/* A pop up list of items used to show autocompleted results */
+
+.autocomplete-results {
+  position: absolute;
+  left: 0;
+  z-index: 99;
+  width: max-content;
+  min-width: 100%;
+  max-height: 20em;
+  overflow-y: auto;
+  font-size: 13px;
+  list-style: none;
+  background: var(--color-canvas-overlay);
+  border: var(--yattho-borderWidth-thin, 1px) solid var(--color-border-default);
+  border-radius: var(--yattho-borderRadius-medium, 6px);
+  box-shadow: var(--color-shadow-medium);
+}
+
+/* One of the items that appears within an autocomplete group
+** Bold black text on white background */
+
+.autocomplete-item {
+  display: block;
+  width: 100%;
+  padding: 4px 8px;
+  overflow: hidden;
+  font-weight: var(--base-text-weight-semibold, 600);
+  color: var(--color-fg-default);
+  text-align: left;
+  text-decoration: none;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  cursor: pointer;
+  background-color: var(--color-canvas-overlay);
+  border: 0;
+}
+
+.autocomplete-item:hover {
+    color: var(--color-fg-on-emphasis);
+    text-decoration: none;
+    background-color: var(--color-accent-emphasis);
+
+    /* Inherit color on all child elements to ensure enough contrast */
+  }
+
+.autocomplete-item:hover * {
+      color: inherit !important;
+    }
+
+.autocomplete-item.selected,
+  .autocomplete-item[aria-selected='true'],
+  .autocomplete-item.navigation-focus {
+    color: var(--color-fg-on-emphasis);
+    text-decoration: none;
+    background-color: var(--color-accent-emphasis);
+
+    /* Inherit color on all child elements to ensure enough contrast */
+  }
+
+.autocomplete-item.selected *, .autocomplete-item[aria-selected='true'] *, .autocomplete-item.navigation-focus * {
+      color: inherit !important;
+    }

data/app/components/yattho/alpha/auto_complete.css.json

@@ -0,0 +1 @@
+{"name":"alpha/auto_complete","selectors":[".autocomplete-label-stacked",".autocomplete-label-inline",".autocomplete-body",".autocomplete-embedded-icon-wrap",".autocomplete-embedded-icon-wrap:focus-within",".autocomplete-embedded-icon-wrap .form-control",".autocomplete-embedded-icon-wrap .form-control:focus",".autocomplete-embedded-icon-wrap .form-control:focus-visible",".autocomplete-results",".autocomplete-item",".autocomplete-item:hover",".autocomplete-item:hover *",".autocomplete-item.selected","\n  .autocomplete-item[aria-selected='true']","\n  .autocomplete-item.navigation-focus",".autocomplete-item.selected *"," .autocomplete-item[aria-selected='true'] *"," .autocomplete-item.navigation-focus *"]}

data/app/components/yattho/alpha/auto_complete.css.map

@@ -0,0 +1 @@
+{"version":3,"sources":["auto_complete.pcss","../../../../lib/postcss_mixins/focusBoxShadowInset.pcss"],"names":[],"mappings":"AAAA,iBAAiB;;AAEjB;mEACmE;;AAEnE,4BAA4B;;AAC5B;EACE,cAAc;EACd,kBAAkB;AACpB;;AAEA,+BAA+B;;AAC/B;EACE,eAAe;EACf,iBAAiB;AACnB;;AAEA,0CAA0C;;AAC1C;EACE;IACE,cAAc;IACd,kBAAkB;EACpB;AACF;;AAEA,kEAAkE;;AAClE;EACE,kBAAkB;EAClB,eAAe;AACjB;;AAEA,6DAA6D;;AAC7D;EACE,oBAAoB;EACpB,gBAAgB;EAChB,mBAAmB;AAsBrB;;AApBE;IACE,oCAAoC;;ICpCtC,oCAAoC;;IACpC,aAAa;;IACb,kDAAmD;EDqCnD;;AAEA;IACE,UAAU;IACV,gBAAgB;IAChB,YAAY;IACZ,gBAAgB;EASlB;;AAPE;MACE,gBAAgB;IAClB;;AAEA;MACE,gBAAgB;IAClB;;AAIJ,8DAA8D;;AAC9D;EACE,kBAAkB;EAClB,OAAO;EACP,WAAW;EACX,kBAAkB;EAClB,eAAe;EACf,gBAAgB;EAChB,gBAAgB;EAChB,eAAe;EACf,gBAAgB;EAChB,uCAAuC;EACvC,6EAA6E;EAC7E,qDAAqD;EACrD,sCAAsC;AACxC;;AAEA;wCACwC;;AAExC;EACE,cAAc;EACd,WAAW;EACX,gBAAgB;EAChB,gBAAgB;EAChB,kDAAkD;EAClD,8BAA8B;EAC9B,gBAAgB;EAChB,qBAAqB;EACrB,uBAAuB;EACvB,mBAAmB;EACnB,eAAe;EACf,6CAA6C;EAC7C,SAAS;AAyBX;;AAvBE;IACE,kCAAkC;IAClC,qBAAqB;IACrB,8CAA8C;;IAE9C,kEAAkE;EAIpE;;AAHE;MACE,yBAAyB;IAC3B;;AAGF;;;IAGE,kCAAkC;IAClC,qBAAqB;IACrB,8CAA8C;;IAE9C,kEAAkE;EAIpE;;AAHE;MACE,yBAAyB;IAC3B","file":"auto_complete.css","sourcesContent":["/* autocomplete */\n\n/* This file can be deprecated when AutoComplete is upstreamed to YVC + rolled out to dotcom https://github.com/github/yattho/issues/796\n** AutoComplete relies on FormControl, Overlay and ActionList CSS */\n\n/* Stacked label (default) */\n.autocomplete-label-stacked {\n  display: block;\n  margin-bottom: 6px;\n}\n\n/* Inline label (non-default) */\n.autocomplete-label-inline {\n  display: inline;\n  margin-right: 6px;\n}\n\n/* Switch to stacked at smaller viewport */\n@media (max-width: 543.98px) {\n  .autocomplete-label-inline {\n    display: block;\n    margin-bottom: 6px;\n  }\n}\n\n/* Wrapper for the input and result elements to ensure alignment */\n.autocomplete-body {\n  position: relative;\n  display: inline;\n}\n\n/* Wrapper and conditional styles for when an icon is added */\n.autocomplete-embedded-icon-wrap {\n  display: inline-flex;\n  padding: 4px 8px;\n  align-items: center;\n\n  &:focus-within {\n    border-color: var(--color-accent-fg);\n\n    @mixin focusBoxShadowInset;\n  }\n\n  & .form-control {\n    padding: 0;\n    margin-left: 8px;\n    border: none;\n    box-shadow: none;\n\n    &:focus {\n      box-shadow: none;\n    }\n\n    &:focus-visible {\n      box-shadow: none;\n    }\n  }\n}\n\n/* A pop up list of items used to show autocompleted results */\n.autocomplete-results {\n  position: absolute;\n  left: 0;\n  z-index: 99;\n  width: max-content;\n  min-width: 100%;\n  max-height: 20em;\n  overflow-y: auto;\n  font-size: 13px;\n  list-style: none;\n  background: var(--color-canvas-overlay);\n  border: var(--yattho-borderWidth-thin, 1px) solid var(--color-border-default);\n  border-radius: var(--yattho-borderRadius-medium, 6px);\n  box-shadow: var(--color-shadow-medium);\n}\n\n/* One of the items that appears within an autocomplete group\n** Bold black text on white background */\n\n.autocomplete-item {\n  display: block;\n  width: 100%;\n  padding: 4px 8px;\n  overflow: hidden;\n  font-weight: var(--base-text-weight-semibold, 600);\n  color: var(--color-fg-default);\n  text-align: left;\n  text-decoration: none;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n  cursor: pointer;\n  background-color: var(--color-canvas-overlay);\n  border: 0;\n\n  &:hover {\n    color: var(--color-fg-on-emphasis);\n    text-decoration: none;\n    background-color: var(--color-accent-emphasis);\n\n    /* Inherit color on all child elements to ensure enough contrast */\n    & * {\n      color: inherit !important;\n    }\n  }\n\n  &.selected,\n  &[aria-selected='true'],\n  &.navigation-focus {\n    color: var(--color-fg-on-emphasis);\n    text-decoration: none;\n    background-color: var(--color-accent-emphasis);\n\n    /* Inherit color on all child elements to ensure enough contrast */\n    & * {\n      color: inherit !important;\n    }\n  }\n}","/* inset box-shadow for form controls */\n@define-mixin focusBoxShadowInset $outlineWidth: 1px, $outlineColor: var(--color-accent-fg) {\n  border-color: var(--color-accent-fg);\n  outline: none;\n  box-shadow: inset 0 0 0 $outlineWidth $outlineColor;\n}"]}

data/app/components/yattho/alpha/auto_complete.pcss

@@ -0,0 +1,118 @@
+/* autocomplete */
+
+/* This file can be deprecated when AutoComplete is upstreamed to YVC + rolled out to dotcom https://github.com/github/yattho/issues/796
+** AutoComplete relies on FormControl, Overlay and ActionList CSS */
+
+/* Stacked label (default) */
+.autocomplete-label-stacked {
+  display: block;
+  margin-bottom: 6px;
+}
+
+/* Inline label (non-default) */
+.autocomplete-label-inline {
+  display: inline;
+  margin-right: 6px;
+}
+
+/* Switch to stacked at smaller viewport */
+@media (max-width: 543.98px) {
+  .autocomplete-label-inline {
+    display: block;
+    margin-bottom: 6px;
+  }
+}
+
+/* Wrapper for the input and result elements to ensure alignment */
+.autocomplete-body {
+  position: relative;
+  display: inline;
+}
+
+/* Wrapper and conditional styles for when an icon is added */
+.autocomplete-embedded-icon-wrap {
+  display: inline-flex;
+  padding: 4px 8px;
+  align-items: center;
+
+  &:focus-within {
+    border-color: var(--color-accent-fg);
+
+    @mixin focusBoxShadowInset;
+  }
+
+  & .form-control {
+    padding: 0;
+    margin-left: 8px;
+    border: none;
+    box-shadow: none;
+
+    &:focus {
+      box-shadow: none;
+    }
+
+    &:focus-visible {
+      box-shadow: none;
+    }
+  }
+}
+
+/* A pop up list of items used to show autocompleted results */
+.autocomplete-results {
+  position: absolute;
+  left: 0;
+  z-index: 99;
+  width: max-content;
+  min-width: 100%;
+  max-height: 20em;
+  overflow-y: auto;
+  font-size: 13px;
+  list-style: none;
+  background: var(--color-canvas-overlay);
+  border: var(--yattho-borderWidth-thin, 1px) solid var(--color-border-default);
+  border-radius: var(--yattho-borderRadius-medium, 6px);
+  box-shadow: var(--color-shadow-medium);
+}
+
+/* One of the items that appears within an autocomplete group
+** Bold black text on white background */
+
+.autocomplete-item {
+  display: block;
+  width: 100%;
+  padding: 4px 8px;
+  overflow: hidden;
+  font-weight: var(--base-text-weight-semibold, 600);
+  color: var(--color-fg-default);
+  text-align: left;
+  text-decoration: none;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  cursor: pointer;
+  background-color: var(--color-canvas-overlay);
+  border: 0;
+
+  &:hover {
+    color: var(--color-fg-on-emphasis);
+    text-decoration: none;
+    background-color: var(--color-accent-emphasis);
+
+    /* Inherit color on all child elements to ensure enough contrast */
+    & * {
+      color: inherit !important;
+    }
+  }
+
+  &.selected,
+  &[aria-selected='true'],
+  &.navigation-focus {
+    color: var(--color-fg-on-emphasis);
+    text-decoration: none;
+    background-color: var(--color-accent-emphasis);
+
+    /* Inherit color on all child elements to ensure enough contrast */
+    & * {
+      color: inherit !important;
+    }
+  }
+}

data/app/components/yattho/alpha/auto_complete.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Yattho
+  module Alpha
+    # 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.
+    # @accessibility
+    #   Always set an accessible label to help the user interact with the component.
+    #
+    #   * `label_text` is required and visible by default.
+    #   * If you must use a non-visible label, set `is_label_visible` to `false`.
+    #   However, please note that a visible label should almost always
+    #   be used unless there is compelling reason not to. A placeholder is not a label.
+    class AutoComplete < Yattho::Component
+      status :deprecated
+
+      # Customizable results list.
+      #
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      renders_one :results, lambda { |**system_arguments|
+        deny_tag_argument(**system_arguments)
+        system_arguments[:tag] = :ul
+        system_arguments[:id] = @list_id
+        system_arguments[:classes] = class_names(
+          "autocomplete-results",
+          system_arguments[:classes]
+        )
+        Yattho::BaseComponent.new(**system_arguments)
+      }
+
+      # Customizable input used to search for results.
+      # It is preferred to use this slot sparingly - it will be created by default if not explicity added.
+      #
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      renders_one :input, lambda { |**system_arguments|
+        sanitized_args = deny_tag_argument(**system_arguments)
+        sanitized_args = deny_single_argument(:autofocus, "autofocus is not allowed for accessibility reasons. See https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus#accessibility_considerations for more information.", **sanitized_args)
+        deny_aria_key(
+          :label,
+          "instead of `aria-label`, include `label_text` and set `is_label_visible` to `false` on the component initializer.",
+          **sanitized_args
+        )
+        deny_single_argument(
+          :id,
+          "`id` will always be set to @input_id.",
+          **sanitized_args
+        )
+        deny_single_argument(
+          :name,
+          "Set @input_name on the component initializer instead with `input_name`.",
+          **sanitized_args
+        )
+        sanitized_args[:id] = @input_id
+        sanitized_args[:name] = @input_name
+        sanitized_args[:tag] = :input
+        sanitized_args[:autocomplete] = "off"
+        sanitized_args[:type] = :text
+        sanitized_args[:classes] = class_names(
+          "form-control",
+          sanitized_args[:classes]
+        )
+        Yattho::BaseComponent.new(**sanitized_args)
+      }
+
+      # @example Default
+      #   @description
+      #     Labels are stacked by default.
+      #   @code
+      #     <%= render(Yattho::Alpha::AutoComplete.new(label_text: "Fruits", src: "/view-components/rails-app/auto_complete?version=alpha", input_id: "fruits-input--default", list_id: "fruits-popup--default")) %>
+      #
+      # @example With inline label
+      #   @description
+      #     Labels can be inline by setting `is_label_inline: true`. However, labels will always become stacked on smaller screen sizes.
+      #   @code
+      #     <%= render(Yattho::Alpha::AutoComplete.new(label_text: "Fruits", src: "/view-components/rails-app/auto_complete?version=alpha", is_label_inline: true, input_id: "fruits-input--inline-label", list_id: "fruits-popup--inline-label")) %>
+      #
+      # @example With non-visible label
+      #   @description
+      #     A non-visible label may be rendered with `is_label_visible: false`, but it is highly discouraged. See <%= link_to_accessibility %>.
+      #   @code
+      #     <%= render(Yattho::Alpha::AutoComplete.new(label_text: "Fruits", src: "/view-components/rails-app/auto_complete?version=alpha", input_id: "fruits-input--non-visible-label", list_id: "fruits-popup--non-visible-label", is_label_visible: false)) %>
+      #
+      # @example With icon
+      #   @description
+      #     To display a search icon, set `with_icon` to `true`.
+      #   @code
+      #     <%= render(Yattho::Alpha::AutoComplete.new(label_text: "Fruits", src: "/view-components/rails-app/auto_complete?version=alpha", list_id: "fruits-popup--icon", input_id: "fruits-input--icon", with_icon: true)) %>
+      #
+      # @example With icon and non-visible label
+      #   <%= render(Yattho::Alpha::AutoComplete.new(label_text: "Fruits", src: "/view-components/rails-app/auto_complete?version=alpha", list_id: "fruits-popup--icon-no-label", input_id: "fruits-input--icon-no-label", with_icon: true, is_label_visible: false)) %>
+      #
+      # @example With clear button
+      #   <%= render(Yattho::Alpha::AutoComplete.new(label_text: "Fruits", src: "/view-components/rails-app/auto_complete?version=alpha", input_id: "fruits-input--clear", list_id: "fruits-popup--clear", is_clearable: true)) %>
+      #
+      # @example With custom classes for the input
+      #   <%= render(Yattho::Alpha::AutoComplete.new(label_text: "Fruits", src: "/view-components/rails-app/auto_complete?version=alpha", input_id: "fruits-input--custom-input", list_id: "fruits-popup--custom-input")) do |component| %>
+      #     <% component.with_input(classes: "custom-class") %>
+      #   <% end %>
+      #
+      # @example With custom classes for the results
+      #   <%= render(Yattho::Alpha::AutoComplete.new(label_text: "Fruits", src: "/view-components/rails-app/auto_complete?version=alpha", input_id: "fruits-input--custom-results", list_id: "fruits-popup--custom-results")) do |component| %>
+      #     <% component.with_results(classes: "custom-class") do %>
+      #       <%= render(Yattho::Alpha::AutoComplete::Item.new(selected: true, value: "apple")) do %>
+      #         Apple
+      #       <% end %>
+      #       <%= render(Yattho::Alpha::AutoComplete::Item.new(value: "orange")) do %>
+      #         Orange
+      #       <% end %>
+      #     <% end %>
+      #   <% end %>
+      #
+      # @param label_text [String] The label of the input.
+      # @param src [String] The route to query.
+      # @param input_id [String] Id of the input element.
+      # @param input_name [String] Optional name of the input element, defaults to `input_id` when not set.
+      # @param list_id [String] Id of the list element.
+      # @param with_icon [Boolean] Controls if a search icon is visible, defaults to `false`.
+      # @param is_label_visible [Boolean] Controls if the label is visible. If `false`, screen reader only text will be added.
+      # @param is_clearable [Boolean] Adds optional clear button.
+      # @param is_label_inline [Boolean] Controls if the label is inline. On smaller screens, label will always become stacked.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(label_text:, src:, list_id:, input_id:, input_name: nil, is_label_visible: true,
+                     is_label_inline: false, with_icon: false, is_clearable: false, **system_arguments)
+        @label_text = label_text
+        @list_id = list_id
+        @input_id = input_id
+        @input_name = input_name || input_id
+        @is_label_visible = is_label_visible
+        @with_icon = with_icon
+        @is_clearable = is_clearable
+        @label_classes = label_classes(is_label_visible: is_label_visible, is_label_inline: is_label_inline)
+        @system_arguments = deny_tag_argument(**system_arguments)
+        @system_arguments[:tag] = "auto-complete"
+        @system_arguments[:src] = src
+        @system_arguments[:for] = list_id
+      end
+
+      # add `input` and `results` without needing to explicitly call them in the view
+      def before_render
+        with_results(classes: "") unless results?
+        with_input(classes: "") unless input?
+      end
+
+      private
+
+      # Private: determines the label classes based on component configration.
+      #
+      # If the label is not visible, return an empty string.
+      #
+      # @param args [Hash] The component configuration.
+      # @return [String] The label classes.
+      def label_classes(**args)
+        return "" if args[:is_label_visible] == false
+
+        args[:is_label_inline] ? "autocomplete-label-inline" : "autocomplete-label-stacked"
+      end
+    end
+  end
+end